@endevops/peppol-schema 0.1.2 → 0.1.4

package/src/constants/transport-profile.ts

@@ -1,5 +1,15 @@
+/**
+ * @description PEPPOL AS4 transport profile identifier for transport profile version 2.0.
+ *
+ * @example
+ *   ```ts
+ *   TRANSPORT_PROFILE; // 'peppol-transport-as4-v2_0'
+ *   ```;
+ */
 export const TRANSPORT_PROFILE = 'peppol-transport-as4-v2_0' as const;
 /**
+ * @description Deprecated alias of {@link TRANSPORT_PROFILE}.
+ *
  * @deprecated
  */
 export const transportProfile = TRANSPORT_PROFILE;

package/src/invoice-response-codes/invoice-response-code-needs-schema.ts

@@ -1 +1,10 @@
+/**
+ * @description Invoice response status codes that require a clarification. The codes are Under query (UQ), Rejected (RE), and Conditionally accepted (CA).
+ * Consumed by {@link withStatusCodes}, where the `status` array must contain at least one entry.
+ *
+ * @example
+ *   ```ts
+ *   invoiceResponseCodeNeedsSchema; // ['UQ', 'RE', 'CA']
+ *   ```;
+ */
 export const invoiceResponseCodeNeedsSchema = ['UQ', 'RE', 'CA'] as const;

package/src/invoice-response-codes/invoice-response-code-not-needs-schema.ts

@@ -1 +1,10 @@
+/**
+ * @description Invoice response status codes that do not require a clarification. The codes are Message acknowledgement (AB), Accepted (AP), In process (IP), and
+ * Paid (PD). Consumed by {@link withoutStatusCodes}, where `status` is optional.
+ *
+ * @example
+ *   ```ts
+ *   invoiceResponseCodeNotNeedsSchema; // ['AB', 'AP', 'IP', 'PD']
+ *   ```;
+ */
 export const invoiceResponseCodeNotNeedsSchema = ['AB', 'AP', 'IP', 'PD'] as const;

package/src/invoice-response-codes/invoice-response-codes-order.ts

@@ -1,5 +1,15 @@
 import type { InvoiceStatusCodesKeys } from '#/values/invoice-status-codes.generated';
 
+/**
+ * @description Map of allowed status transitions for an invoice response, keyed by the current status code. Each value lists the status codes that may follow the
+ * key. Keys and values are {@link InvoiceStatusCodesKeys}. The terminal statuses PD and RE map to empty arrays.
+ *
+ * @example
+ *   ```ts
+ *   invoiceResponseCodesOrder.UQ; // ['CA', 'AP', 'RE']
+ *   invoiceResponseCodesOrder.PD; // []
+ *   ```;
+ */
 export const invoiceResponseCodesOrder: Record<InvoiceStatusCodesKeys, Array<InvoiceStatusCodesKeys>> = {
   AB: ['IP', 'UQ', 'AP', 'CA', 'PD', 'RE'],
   AP: ['PD'],

package/src/peppol-validations/add-piva.ts

@@ -2,6 +2,18 @@
 
 /**
  * @description Helper function for calculating weighted sum for Italian PIVA validation.
+ *
+ * @example
+ *   ```ts
+ *   addPIVA('123', 0); // 8
+ *   ```;
+ *
+ * @param arg - The digit string to sum, processed one character at a time.
+ * @param pari - Parity flag toggled at each recursion; `1` maps the digit through the `0246813579` table, `0` keeps it as is.
+ *
+ * @returns The weighted sum, or `0` when `arg` contains a non-digit.
+ *
+ * @see {@link checkPIVA}
  */
 export function addPIVA(arg: string, pari: number): number {
   if (!/^\d+$/.test(arg)) return 0;

package/src/peppol-validations/check-cf.ts

@@ -3,6 +3,17 @@ import { normalizeSpace } from './normalize-space.ts';
 
 /**
  * @description Validates both 16 and 11 character Italian fiscal codes.
+ *
+ * @example
+ *   ```ts
+ *   checkCF('RSSMRA80A01H501U'); // true
+ *   ```;
+ *
+ * @param arg - The fiscal code to validate. Whitespace is normalised first.
+ *
+ * @returns `true` when the normalised code is a valid 16 character personal fiscal code or an 11 digit VAT code, otherwise `false`.
+ *
+ * @see {@link checkCF16}
  */
 export function checkCF(arg: string): boolean {
   const s = normalizeSpace(arg);

package/src/peppol-validations/check-cf16.ts

@@ -2,6 +2,18 @@ import { normalizeSpace } from './normalize-space.ts';
 
 /**
  * @description Validates 16-character Italian fiscal codes.
+ *
+ * @example
+ *   ```ts
+ *   checkCF16('RSSMRA80A01H501U'); // true
+ *   ```;
+ *
+ * @param arg - The fiscal code to validate. Whitespace is normalised first.
+ *
+ * @returns `true` when the normalised code is 16 characters and matches `{6 letters}{2 digits}{letter}{2 digits}{letter}{3 digits}{letter}`,
+ *   otherwise `false`.
+ *
+ * @see {@link checkCF}
  */
 export function checkCF16(arg: string): boolean {
   const s = normalizeSpace(arg);

package/src/peppol-validations/check-piva-se-it.ts

@@ -2,6 +2,17 @@ import { checkPIVA } from './check-piva.ts';
 
 /**
  * @description Validates Italian VAT numbers with IT prefix.
+ *
+ * @example
+ *   ```ts
+ *   checkPIVAseIT('IT00743110157'); // true
+ *   ```;
+ *
+ * @param arg - The VAT identifier including its two letter country prefix.
+ *
+ * @returns `true` when the prefix is not `IT`, or when the 11 digit Italian part passes {@link checkPIVA}; otherwise `false`.
+ *
+ * @see {@link checkPIVA}
  */
 export function checkPIVAseIT(arg: string): boolean {
   const paese = arg.substring(0, 2);

package/src/peppol-validations/check-piva.ts

@@ -2,6 +2,17 @@ import { addPIVA } from './add-piva.ts';
 
 /**
  * @description Validates Italian VAT numbers (PIVA)
+ *
+ * @example
+ *   ```ts
+ *   checkPIVA('00743110157'); // 0
+ *   ```;
+ *
+ * @param arg - The Italian VAT number without the `IT` prefix.
+ *
+ * @returns `0` when valid, otherwise the non-zero remainder of {@link addPIVA}, or `1` when `arg` contains a non-digit.
+ *
+ * @see {@link addPIVA}
  */
 export function checkPIVA(arg: string): number {
   if (!/^\d+$/.test(arg)) return 1;

package/src/peppol-validations/check-se-orgnr.ts

@@ -2,6 +2,15 @@ import { normalizeSpace } from './normalize-space.ts';
 
 /**
  * @description Validates Swedish organization numbers (0007)
+ *
+ * @example
+ *   ```ts
+ *   checkSEOrgnr('5560160680'); // true
+ *   ```;
+ *
+ * @param number - The organization number to validate. Whitespace is normalised first.
+ *
+ * @returns `true` when the normalised number is 10 digits and its Luhn check digit matches, otherwise `false`.
  */
 export function checkSEOrgnr(number: string): boolean {
   const s = normalizeSpace(number);

package/src/peppol-validations/greek-tin-verification.ts

@@ -1,5 +1,14 @@
 /**
  * @description Greek TIN verification.
+ *
+ * @example
+ *   ```ts
+ *   greekTinVerification('123456783'); // true
+ *   ```;
+ *
+ * @param val - The nine digit Greek tax identification number.
+ *
+ * @returns `true` when the value is nine digits and the computed checksum matches the last digit, otherwise `false`.
  */
 export function greekTinVerification(val: string): boolean {
   if (!/^\d{9}$/.test(val)) return false;

package/src/peppol-validations/is-valid-abn.ts

@@ -2,6 +2,15 @@ import { normalizeSpace } from './normalize-space.ts';
 
 /**
  * @description Australian Business Number (ABN) validation.
+ *
+ * @example
+ *   ```ts
+ *   isValidABN('51 824 753 556'); // true
+ *   ```;
+ *
+ * @param val - The ABN to validate. Whitespace is normalised first.
+ *
+ * @returns `true` when the normalised value is 11 digits and the weighted checksum is divisible by 89, otherwise `false`.
  */
 export function isValidABN(val: string): boolean {
   const s = normalizeSpace(val);

package/src/peppol-validations/is-valid-gln.ts

@@ -1,5 +1,15 @@
 /**
  * @description [GLN](https://en.wikipedia.org/wiki/Global_Location_Number) check (GS1)
+ *
+ * @example
+ *   ```ts
+ *   isValidGLN('1234567890128'); // { success: true }
+ *   ```;
+ *
+ * @param val - The GLN to validate. Whitespace is stripped first.
+ *
+ * @returns `{ success: true }` when the computed check digit matches the last digit, otherwise `{ success: false, expected, actual }` with the
+ *   computed and supplied check digits.
  */
 export function isValidGLN(val: string): { success: true } | { success: false; expected: number; actual: number } {
   const value = (val ?? '').replace(/\s+/g, '');

package/src/peppol-validations/is-valid-iban.ts

@@ -2,6 +2,16 @@ import { normalizeSpace } from './normalize-space.ts';
 
 /**
  * @description IBAN validation using mod 97 algorithm.
+ *
+ * @example
+ *   ```ts
+ *   isValidIBAN('GB82 WEST 1234 5698 7654 32'); // true
+ *   ```;
+ *
+ * @param iban - The IBAN to validate, with or without spaces.
+ *
+ * @returns `true` when the normalised value matches the `{2 letters}{2 digits}{up to 30 alphanumerics}` shape and its mod 97 remainder is 1,
+ *   otherwise `false`.
  */
 export function isValidIBAN(iban: string): boolean {
   const s = normalizeSpace(iban).replace(/[ \t\r\n]/g, '');

package/src/peppol-validations/is-valid-mod11.ts

@@ -2,6 +2,15 @@ import { normalizeSpace } from './normalize-space.ts';
 
 /**
  * @description Validates Norwegian organization numbers using mod11 algorithm.
+ *
+ * @example
+ *   ```ts
+ *   isValidMod11('923609016'); // true
+ *   ```;
+ *
+ * @param val - The organization number to validate. Whitespace is normalised first.
+ *
+ * @returns `true` when the normalised value is at least two digits and its mod 11 check digit matches, otherwise `false`.
  */
 export function isValidMod11(val: string): boolean {
   const s = normalizeSpace(val);

package/src/peppol-validations/is-valid-mod97-0208.ts

@@ -2,6 +2,16 @@ import { normalizeSpace } from './normalize-space.ts';
 
 /**
  * @description Belgian enterprise number validation (mod 97-0208)
+ *
+ * @example
+ *   ```ts
+ *   isValidMod97_0208('0123456749'); // { success: true }
+ *   ```;
+ *
+ * @param val - The enterprise number to validate. Whitespace is normalised first.
+ *
+ * @returns `{ success: true }` when the last two digits equal `97 - (first eight digits % 97)`, otherwise `{ success: false, expected, actual }` with
+ *   the computed and supplied check digits.
  */
 export function isValidMod97_0208(val: string): { success: true } | { success: false; expected: number; actual: number } {
   const s = normalizeSpace(val);

package/src/peppol-validations/luhn-check.ts

@@ -2,6 +2,15 @@ import { normalizeSpace } from './normalize-space.ts';
 
 /**
  * @description Luhn algorithm check (used for credit card validation)
+ *
+ * @example
+ *   ```ts
+ *   luhnCheck('4242424242424242'); // true
+ *   ```;
+ *
+ * @param number - The numeric string to check. Whitespace is normalised first.
+ *
+ * @returns `true` when the value contains only digits and its Luhn checksum is divisible by 10, otherwise `false`.
  */
 export function luhnCheck(number: string): boolean {
   const s = normalizeSpace(number);

package/src/schemas/fields/default-customization-id.ts

@@ -1 +1,10 @@
+/**
+ * @description The default PEPPOL BIS Billing 3.0 customization identifier, which identifies the EN 16931 compliant billing rule set. Used as the decoding default
+ * for the `customizationId` field of {@link PeppolBillingBase}.
+ *
+ * @example
+ *   ```ts
+ *   DEFAULT_CUSTOMIZATION_ID; // 'urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0'
+ *   ```;
+ */
 export const DEFAULT_CUSTOMIZATION_ID = 'urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0' as const;

package/src/schemas/fields/default-profile-id.ts

@@ -1 +1,10 @@
+/**
+ * @description The default PEPPOL BIS Billing 3.0 profile identifier, which identifies the billing process the document follows. Used as the decoding default for
+ * the `profileId` field of {@link PeppolBillingBase}.
+ *
+ * @example
+ *   ```ts
+ *   DEFAULT_PROFILE_ID; // 'urn:fdc:peppol.eu:2017:poacc:billing:01:1.0'
+ *   ```;
+ */
 export const DEFAULT_PROFILE_ID = 'urn:fdc:peppol.eu:2017:poacc:billing:01:1.0' as const;

package/src/schemas/fields/peppol-additional-document-reference-schema.ts

@@ -3,8 +3,19 @@ import { Schema } from 'effect';
 import { PeppolBinaryObject } from '#/schemas/fields/peppol-binary-object-schema.ts';
 import { PeppolIdentifier } from '#/schemas/fields/peppol-identifier-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { additionalDocumentReferenceCodeSchema } from '#/schemas/values/additional-document-reference-code-schema.ts';
+import { PeppolAdditionalDocumentReferenceCode } from '#/schemas/values/additional-document-reference-code-schema.ts';
 
+/**
+ * @description A reference to a supporting document that is stored outside the Invoice, identified by a URI. Wraps the `cac:ExternalReference` element of an
+ * attachment group.
+ *
+ * @example
+ *   ```ts
+ *   { uri: 'http://www.example.com/index.html' }
+ *   ```;
+ *
+ * @see {@link PeppolAttachment}
+ */
 export class PeppolAttachmentExternalReference extends opaque<PeppolAttachmentExternalReference>()(
   Schema.Struct({
     /**
@@ -22,6 +33,23 @@ export class PeppolAttachmentExternalReference extends opaque<PeppolAttachmentEx
   })
 ) {}
 
+/**
+ * @description The attachment of a supporting document to the Invoice, either embedded as a Base64 binary object or referenced by URI. Wraps the `cac:Attachment`
+ * element of an additional supporting document.
+ *
+ * @example
+ *   ```ts
+ *   {
+ *     embeddedDocumentBinaryObject: {
+ *       content: 'aHR0cHM6Ly90ZXN0LXZlZmEuZGlmaS5uby9wZXBwb2xiaXM=',
+ *       mimeCode: 'text/csv',
+ *       filename: 'Hours - spent.csv'
+ *     }
+ *   }
+ *   ```;
+ *
+ * @see {@link PeppolAdditionalDocumentReference}
+ */
 export class PeppolAttachment extends opaque<PeppolAttachment>()(
   Schema.Struct({
     /**
@@ -46,6 +74,17 @@ export class PeppolAttachment extends opaque<PeppolAttachment>()(
   })
 ) {}
 
+/**
+ * @description The identifier of an additional supporting document, an invoiced object reference or a project reference, together with an optional identification
+ * scheme identifier.
+ *
+ * @example
+ *   ```ts
+ *   { id: '9873242' }
+ *   ```;
+ *
+ * @see {@link PeppolAdditionalDocumentReference}
+ */
 export class PeppolId extends opaque<PeppolId>()(
   Schema.Struct({
     /**
@@ -64,7 +103,7 @@ export class PeppolId extends opaque<PeppolId>()(
      *
      * @name `@schemeID`
      */
-    schemeId: Schema.optional(additionalDocumentReferenceCodeSchema),
+    schemeId: Schema.optional(PeppolAdditionalDocumentReferenceCode),
   })
 ) {}
 

package/src/schemas/fields/peppol-address-schema.ts

@@ -1,8 +1,18 @@
 import { Schema } from 'effect';
 
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { peppolCountryCodeSchema } from '#/schemas/values/peppol-country-code-schema.ts';
+import { PeppolCountryCodeValue } from '#/schemas/values/peppol-country-code-schema.ts';
 
+/**
+ * @description An additional address line that supplements the main address line. Wraps the `cac:AddressLine` element, whose `cbc:Line` value carries the text.
+ *
+ * @example
+ *   ```ts
+ *   { line: 'Building 23' }
+ *   ```;
+ *
+ * @see {@link PeppolAddress}
+ */
 export class PeppolAddressLine extends opaque<PeppolAddressLine>()(
   Schema.Struct({
     /**
@@ -16,6 +26,16 @@ export class PeppolAddressLine extends opaque<PeppolAddressLine>()(
   })
 ) {}
 
+/**
+ * @description The country of an address, expressed as a two-letter ISO 3166-1 alpha-2 code. Wraps the `cac:Country` element and its `cbc:IdentificationCode`.
+ *
+ * @example
+ *   ```ts
+ *   { identificationCode: 'GB' }
+ *   ```;
+ *
+ * @see {@link PeppolAddress}
+ */
 export class PeppolCountryCode extends opaque<PeppolCountryCode>()(
   Schema.Struct({
     /**
@@ -28,11 +48,14 @@ export class PeppolCountryCode extends opaque<PeppolCountryCode>()(
      *
      * @name `cbc:IdentificationCode`
      */
-    identificationCode: peppolCountryCodeSchema,
+    identificationCode: PeppolCountryCodeValue,
   })
 ) {}
 
 /**
+ * @description The postal address of a party, used for the seller, buyer, payee and delivery locations. Carries the street lines, city, postal zone, country
+ * subdivision, country code and optional additional address lines.
+ *
  * @summary Postal address
  *
  * @name `cac:PostalAddress`

package/src/schemas/fields/peppol-allowance-charge-schema.ts

@@ -3,10 +3,20 @@ import { Effect, Schema } from 'effect';
 import { BaseLineAllowanceCharge } from '#/schemas/fields/peppol-line-allowance-charge-schema.ts';
 import { PeppolTaxCategory } from '#/schemas/fields/peppol-tax-category-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { allowanceChargeReasonCodeSchema } from '#/schemas/values/allowance-charge-reason-code-schema.ts';
-import { chargeReasonCodeSchema } from '#/schemas/values/charge-reason-code-schema.ts';
-import { peppolDutyTaxFeeCategorySchema } from '#/schemas/values/duty-tax-fee-category-schema.ts';
+import { PeppolAllowanceChargeReasonCode } from '#/schemas/values/allowance-charge-reason-code-schema.ts';
+import { PeppolChargeReasonCode } from '#/schemas/values/charge-reason-code-schema.ts';
+import { PeppolDutyTaxFeeCategoryCode } from '#/schemas/values/duty-tax-fee-category-schema.ts';
 
+/**
+ * @description The identifier of the tax scheme that applies to a document level allowance or charge. Defaults to `VAT` when the value is absent.
+ *
+ * @example
+ *   ```ts
+ *   { id: 'VAT' }
+ *   ```;
+ *
+ * @see {@link PeppolTaxCategory}
+ */
 export class PeppolTaxCategoryTaxSchemeId extends opaque<PeppolTaxCategoryTaxSchemeId>()(
   Schema.Struct({
     /**
@@ -18,6 +28,22 @@ export class PeppolTaxCategoryTaxSchemeId extends opaque<PeppolTaxCategoryTaxSch
   })
 ) {}
 
+/**
+ * @description Shared fields for a document level allowance or charge. Combines the common line allowance and charge fields with the tax category that applies to
+ * the document level amount.
+ *
+ * @example
+ *   ```ts
+ *   {
+ *     amount: { value: 25, currencyId: 'EUR' },
+ *     chargeIndicator: true,
+ *     allowanceChargeReason: 'Insurance',
+ *     taxCategory: { id: 'S', percent: 25, taxSchemeId: { id: 'VAT' } }
+ *   }
+ *   ```;
+ *
+ * @see {@link PeppolAllowanceCharge}
+ */
 export class BaseAllowanceCharge extends opaque<BaseAllowanceCharge>()(
   Schema.Struct({
     ...BaseLineAllowanceCharge.fields,
@@ -36,7 +62,7 @@ export class BaseAllowanceCharge extends opaque<BaseAllowanceCharge>()(
            *
            * @name `cbc:ID`
            */
-          id: peppolDutyTaxFeeCategorySchema,
+          id: PeppolDutyTaxFeeCategoryCode,
           /**
            * @description The VAT rate, represented as percentage that applies to the document level allowance or charge.
            *
@@ -57,13 +83,24 @@ export class BaseAllowanceCharge extends opaque<BaseAllowanceCharge>()(
   })
 ) {}
 
+/**
+ * @description A document level allowance, marked by a `cbc:ChargeIndicator` of `false`. Adds an allowance reason code to the shared document level allowance and
+ * charge fields.
+ *
+ * @example
+ *   ```ts
+ *   { amount: { value: 200, currencyId: 'EUR' }, chargeIndicator: false, allowanceChargeReasonCode: '95' }
+ *   ```;
+ *
+ * @see {@link PeppolAllowanceCharge}
+ */
 export class PeppolAllowance extends opaque<PeppolAllowance>()(
   Schema.Struct({
     ...BaseAllowanceCharge.fields,
     /**
      * @name cbc:AllowanceChargeReasonCode
      */
-    allowanceChargeReasonCode: Schema.optional(allowanceChargeReasonCodeSchema),
+    allowanceChargeReasonCode: Schema.optional(PeppolAllowanceChargeReasonCode),
     /**
      * @name cbc:ChargeIndicator
      *
@@ -75,13 +112,24 @@ export class PeppolAllowance extends opaque<PeppolAllowance>()(
   })
 ) {}
 
+/**
+ * @description A document level charge, marked by a `cbc:ChargeIndicator` of `true`. Adds a charge reason code to the shared document level allowance and charge
+ * fields.
+ *
+ * @example
+ *   ```ts
+ *   { amount: { value: 25, currencyId: 'EUR' }, chargeIndicator: true, allowanceChargeReasonCode: 'AA' }
+ *   ```;
+ *
+ * @see {@link PeppolAllowanceCharge}
+ */
 export class PeppolCharge extends opaque<PeppolCharge>()(
   Schema.Struct({
     ...BaseAllowanceCharge.fields,
     /**
      * @name cbc:AllowanceChargeReasonCode
      */
-    allowanceChargeReasonCode: Schema.optional(chargeReasonCodeSchema),
+    allowanceChargeReasonCode: Schema.optional(PeppolChargeReasonCode),
     /**
      * @name cbc:ChargeIndicator
      *
@@ -94,11 +142,19 @@ export class PeppolCharge extends opaque<PeppolCharge>()(
 ) {}
 
 /**
+ * @description A document level allowance or charge, selected by the `cbc:ChargeIndicator` value: `false` selects an allowance, `true` selects a charge.
+ *
  * @summary Allowance/Charge
  *
  * @name cac:AllowanceCharge
  */
-export const peppolAllowanceChargeSchema = Schema.Union([PeppolAllowance, PeppolCharge]).annotate({ message: 'unable to decode allowance charge' });
+export class PeppolAllowanceCharge extends opaque<PeppolAllowanceCharge>()(
+  Schema.Union([PeppolAllowance, PeppolCharge]).annotate({ message: 'unable to decode allowance charge' })
+) {}
 
-export type PeppolAllowanceCharge = Schema.Schema.Type<typeof peppolAllowanceChargeSchema>;
-export type PeppolAllowanceChargeEncoded = Schema.Codec.Encoded<typeof peppolAllowanceChargeSchema>;
+/**
+ * @description Encoded form of {@link PeppolAllowanceCharge} produced by the Effect Schema codec.
+ *
+ * @see {@link PeppolAllowanceCharge}
+ */
+export type PeppolAllowanceChargeEncoded = Schema.Codec.Encoded<typeof PeppolAllowanceCharge>;

package/src/schemas/fields/peppol-amount-schema.ts

@@ -1,9 +1,17 @@
 import { Schema } from 'effect';
 
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { currencyCodeSchema } from '#/schemas/values/currency-code-schema.ts';
+import { PeppolCurrencyCode } from '#/schemas/values/currency-code-schema.ts';
 
 /**
+ * @description A monetary amount paired with the currency it is expressed in. Wraps a `cbc:*` amount element whose `@currencyID` attribute names the currency and
+ * whose text is the value.
+ *
+ * @example
+ *   ```ts
+ *   { currencyId: 'EUR', value: 4500.0 }
+ *   ```;
+ *
  * @summary Monetary amount with mandatory currency
  *
  * @name cbc:* (+ @currencyID)
@@ -13,11 +21,16 @@ export class PeppolAmount extends opaque<PeppolAmount>()(
     /**
      * @name \@currencyID
      */
-    currencyId: currencyCodeSchema,
+    currencyId: PeppolCurrencyCode,
     /**
      * @name #text (value)
      */
     value: Schema.Finite,
   })
 ) {}
+/**
+ * @description Encoded form of {@link PeppolAmount} produced by the Effect Schema codec. Fields mirror the decoded shape.
+ *
+ * @see {@link PeppolAmount}
+ */
 export interface PeppolAmountEncoded extends Schema.Codec.Encoded<typeof PeppolAmount> {}

package/src/schemas/fields/peppol-base-line-schema.ts

@@ -3,11 +3,21 @@ import { Effect, Schema } from 'effect';
 import { PeppolAmount } from '#/schemas/fields/peppol-amount-schema.ts';
 import { PeppolIdentifier } from '#/schemas/fields/peppol-identifier-schema.ts';
 import { PeppolInvoiceLinePeriod } from '#/schemas/fields/peppol-invoice-line-period-schema.ts';
-import { peppolLineAllowanceChargeSchema } from '#/schemas/fields/peppol-line-allowance-charge-schema.ts';
+import { PeppolLineAllowanceCharge } from '#/schemas/fields/peppol-line-allowance-charge-schema.ts';
 import { PeppolLineItem } from '#/schemas/fields/peppol-line-item-schema.ts';
 import { PeppolLinePrice } from '#/schemas/fields/peppol-line-price-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
+/**
+ * @description A reference to the order line that the Invoice line fulfils. Wraps the `cac:OrderLineReference` element and its `cbc:LineID`.
+ *
+ * @example
+ *   ```ts
+ *   { lineId: '123' }
+ *   ```;
+ *
+ * @see {@link PeppolBaseLine}
+ */
 export class PeppolOrderLineReference extends opaque<PeppolOrderLineReference>()(Schema.Struct({ lineId: Schema.String })) {}
 
 /**
@@ -37,7 +47,7 @@ export class PeppolBaseLine extends opaque<PeppolBaseLine>()(
      *
      * @cardinality 0..n
      */
-    allowanceCharges: Schema.optional(Schema.Array(peppolLineAllowanceChargeSchema)),
+    allowanceCharges: Schema.optional(Schema.Array(PeppolLineAllowanceCharge)),
     /**
      * @summary Line object identifier
      *

package/src/schemas/fields/peppol-billing-reference-schema.ts

@@ -3,6 +3,17 @@ import { Schema } from 'effect';
 import { PeppolIsoDateString } from '#/schemas/peppol-iso-date-string.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
+/**
+ * @description A reference to an Invoice that was previously sent by the Seller, carrying the preceding invoice number and, when the number is not unique, its
+ * issue date. Wraps the `cac:InvoiceDocumentReference` element.
+ *
+ * @example
+ *   ```ts
+ *   { id: 'inv123', issueDate: '2017-09-15' }
+ *   ```;
+ *
+ * @see {@link PeppolBillingReference}
+ */
 export class PeppolInvoiceDocumentReference extends opaque<PeppolInvoiceDocumentReference>()(
   Schema.Struct({
     /**
@@ -33,6 +44,8 @@ export class PeppolInvoiceDocumentReference extends opaque<PeppolInvoiceDocument
 ) {}
 
 /**
+ * @description A reference to a preceding Invoice, used when the Invoice corrects or replaces an earlier one. Wraps the `cac:BillingReference` element.
+ *
  * @summary PRECEDING INVOICE REFERENCE (0..n)
  *
  * @name cac:BillingReference