@endevops/peppol-schema 0.1.3 → 0.1.5

package/src/decoders/fields/decode-invoice-message-document-party.ts

@@ -1,7 +1,7 @@
 import { Effect, Predicate } from 'effect';
 
 import type { XmlNode } from '#/helpers/get-prop.ts';
-import type { PeppolInvoiceDocumentResponseParty } from '#/schemas/peppol-invoice-response-schema.ts';
+import type { PeppolInvoiceResponseDocumentResponseParty } from '#/schemas/peppol-invoice-response-schema.ts';
 import type { RecursivePartial } from '#/types.ts';
 
 import { decodeIdentifier } from '#/decoders/fields/decode-identifier.ts';
@@ -11,7 +11,7 @@ import { strOrUnd } from '#/helpers/str-or-und.ts';
 export const decodeInvoiceMessageDocumentParty = Effect.fn(function* (
   party: XmlNode,
   ...path: Array<string>
-): Effect.fn.Return<RecursivePartial<PeppolInvoiceDocumentResponseParty> | undefined> {
+): Effect.fn.Return<RecursivePartial<PeppolInvoiceResponseDocumentResponseParty> | undefined> {
   const val = yield* getProp(party, ...path);
   if (Predicate.isNullish(val)) return undefined;
   const partyName = yield* getProp(val, 'cac:PartyName');

package/src/decoders/fields/decode-parties-tax-scheme.ts

@@ -1,7 +1,7 @@
 import { Effect, Predicate } from 'effect';
 
 import type { XmlNode } from '#/helpers/get-prop.ts';
-import type { PeppolPartyTaxSchema } from '#/schemas/fields/peppol-party-tax-scheme-schema.ts';
+import type { PeppolPartyTaxScheme } from '#/schemas/fields/peppol-party-tax-scheme-schema.ts';
 import type { RecursivePartial } from '#/types.ts';
 
 import { decodePartyTaxScheme } from '#/decoders/fields/decode-party-tax-scheme.ts';
@@ -10,7 +10,7 @@ import { getArray } from '#/helpers/get-array.ts';
 export const decodePartiesTaxScheme = Effect.fn(function* (
   doc: XmlNode,
   ...path: Array<string>
-): Effect.fn.Return<RecursivePartial<Array<PeppolPartyTaxSchema>> | undefined> {
+): Effect.fn.Return<RecursivePartial<Array<PeppolPartyTaxScheme>> | undefined> {
   const node = yield* getArray(doc, ...path);
   if (node.length === 0) return undefined;
 

package/src/decoders/fields/decode-party-legal-entity.ts

@@ -1,7 +1,7 @@
 import { Effect, Predicate } from 'effect';
 
 import type { XmlNode } from '#/helpers/get-prop.ts';
-import type { PeppolPartyLegalEntitySchema } from '#/schemas/fields/peppol-party-legal-entity-schema.ts';
+import type { PeppolPartyLegalEntity } from '#/schemas/fields/peppol-party-legal-entity-schema.ts';
 import type { RecursivePartial } from '#/types.ts';
 
 import { decodeIdentifier } from '#/decoders/fields/decode-identifier.ts';
@@ -11,7 +11,7 @@ import { strOrUnd } from '#/helpers/str-or-und.ts';
 export const decodePartyLegalEntity = Effect.fn(function* (
   node: XmlNode,
   ...path: Array<string>
-): Effect.fn.Return<RecursivePartial<PeppolPartyLegalEntitySchema> | undefined> {
+): Effect.fn.Return<RecursivePartial<PeppolPartyLegalEntity> | undefined> {
   const partyLegalEntityNode = yield* getProp(node, ...path);
   if (Predicate.isNullish(partyLegalEntityNode)) return undefined;
 

package/src/decoders/fields/decode-party-tax-scheme.ts

@@ -1,7 +1,7 @@
 import { Effect, Predicate } from 'effect';
 
 import type { XmlNode } from '#/helpers/get-prop.ts';
-import type { PeppolPartyTaxSchema } from '#/schemas/fields/peppol-party-tax-scheme-schema.ts';
+import type { PeppolPartyTaxScheme } from '#/schemas/fields/peppol-party-tax-scheme-schema.ts';
 import type { RecursivePartial } from '#/types.ts';
 
 import { decodeSimpleIdentifer } from '#/decoders/fields/decode-simple-identifier.ts';
@@ -11,7 +11,7 @@ import { strOrUnd } from '#/helpers/str-or-und.ts';
 export const decodePartyTaxScheme = Effect.fn(function* (
   doc: XmlNode,
   ...path: Array<string>
-): Effect.fn.Return<RecursivePartial<PeppolPartyTaxSchema> | undefined> {
+): Effect.fn.Return<RecursivePartial<PeppolPartyTaxScheme> | undefined> {
   const node = yield* getProp(doc, ...path);
   if (Predicate.isNullish(node)) return undefined;
 

package/src/decoders/fields/decode-tax-category.ts

@@ -12,7 +12,7 @@ import { strOrUnd } from '#/helpers/str-or-und.ts';
 export const decodeTaxCategory = Effect.fn(function* (
   doc: XmlNode,
   ...path: Array<string>
-): Effect.fn.Return<RecursivePartial<PeppolAllowanceCharge['taxCategory']> | undefined> {
+): Effect.fn.Return<RecursivePartial<(typeof PeppolAllowanceCharge.Type)['taxCategory']> | undefined> {
   const taxCategory = yield* getProp(doc, ...path);
   if (Predicate.isNullish(taxCategory)) {
     return undefined;

package/src/decoders/fields/decode-tax-representative-party.ts

@@ -1,7 +1,7 @@
 import { Effect, Predicate } from 'effect';
 
 import type { XmlNode } from '#/helpers/get-prop.ts';
-import type { PeppolTaxRepresentativeParty } from '#/schemas/fields/peppol-tax-representative-schema.ts';
+import type { PeppolTaxRepresentative } from '#/schemas/fields/peppol-tax-representative-schema.ts';
 import type { RecursivePartial } from '#/types.ts';
 
 import { decodeAddress } from '#/decoders/fields/decode-address.ts';
@@ -12,7 +12,7 @@ import { strOrUnd } from '#/helpers/str-or-und.ts';
 export const decodeTaxRepresentativeParty = Effect.fn(function* (
   doc: XmlNode,
   ...path: Array<string>
-): Effect.fn.Return<RecursivePartial<PeppolTaxRepresentativeParty> | undefined> {
+): Effect.fn.Return<RecursivePartial<PeppolTaxRepresentative> | undefined> {
   const taxRepresentative = yield* getProp(doc, ...path);
   if (Predicate.isNullish(taxRepresentative)) return undefined;
 

package/src/decoders/fields/encode-message-party.ts

@@ -2,14 +2,14 @@ import { Effect, Predicate } from 'effect';
 
 import type { PeppolContact } from '#/schemas/fields/peppol-contact-schema.ts';
 import type { PeppolIdentifier } from '#/schemas/fields/peppol-identifier-schema.ts';
-import type { PeppolInvoiceDocumentResponseParty, PeppolInvoiceResponseParty } from '#/schemas/peppol-invoice-response-schema.ts';
+import type { PeppolInvoiceResponseDocumentResponseParty, PeppolInvoiceResponseParty } from '#/schemas/peppol-invoice-response-schema.ts';
 import type { PeppolMessageLevelResponseParty } from '#/schemas/peppol-message-level-response-party-schema.ts';
 
 import { encodeContact } from '#/decoders/fields/encode-contact.ts';
 import { encodeIdentifier } from '#/decoders/fields/encode-identifier.ts';
 import { encodePartyLegalEntity } from '#/decoders/fields/encode-party-legal-entity.ts';
 
-type ResponseParty = PeppolMessageLevelResponseParty | PeppolInvoiceResponseParty | PeppolInvoiceDocumentResponseParty;
+type ResponseParty = PeppolMessageLevelResponseParty | PeppolInvoiceResponseParty | PeppolInvoiceResponseDocumentResponseParty;
 
 /**
  * @description The response party union exposes different fields per variant; reading the optional ones through a shared view keeps the encoder branch-free.

package/src/decoders/fields/encode-parties-tax-scheme.ts

@@ -1,16 +1,16 @@
 import { Effect, Predicate } from 'effect';
 
 import type { XmlNode } from '#/helpers/get-prop.ts';
-import type { PeppolPartyTaxSchema } from '#/schemas/fields/peppol-party-tax-scheme-schema.ts';
+import type { PeppolPartyTaxScheme } from '#/schemas/fields/peppol-party-tax-scheme-schema.ts';
 
 import { encodePartyTaxScheme } from '#/decoders/fields/encode-party-tax-scheme.ts';
 
-export const encodePartiesTaxScheme = Effect.fn(function* (partiesTaxScheme: Array<PeppolPartyTaxSchema> | undefined): Effect.fn.Return<XmlNode> {
+export const encodePartiesTaxScheme = Effect.fn(function* (partiesTaxScheme: Array<PeppolPartyTaxScheme> | undefined): Effect.fn.Return<XmlNode> {
   if (Predicate.isNullish(partiesTaxScheme) || partiesTaxScheme.length === 0) return undefined;
 
   return yield* Effect.forEach(
     partiesTaxScheme,
-    Effect.fn(function* (partyTaxScheme: PeppolPartyTaxSchema) {
+    Effect.fn(function* (partyTaxScheme: PeppolPartyTaxScheme) {
       return yield* encodePartyTaxScheme(partyTaxScheme);
     })
   );

package/src/decoders/fields/encode-party-legal-entity.ts

@@ -3,7 +3,7 @@ import { Effect } from 'effect';
 import { encodeIdentifier } from '#/decoders/fields/encode-identifier.ts';
 
 export const encodePartyLegalEntity = Effect.fn(function* (legalEntity: {
-  registrationName?: string;
+  registrationName?: string | undefined;
   companyId?: Parameters<typeof encodeIdentifier>[0];
   companyLegalForm?: string | undefined;
 }) {

package/src/decoders/fields/encode-party-tax-scheme.ts

@@ -1,11 +1,11 @@
 import { Effect, Predicate } from 'effect';
 
 import type { XmlNode } from '#/helpers/get-prop.ts';
-import type { PeppolPartyTaxSchema } from '#/schemas/fields/peppol-party-tax-scheme-schema.ts';
+import type { PeppolPartyTaxScheme } from '#/schemas/fields/peppol-party-tax-scheme-schema.ts';
 
 import { encodeSimpleIdentifier } from '#/decoders/fields/encode-simple-identifier.ts';
 
-export const encodePartyTaxScheme = Effect.fn(function* (partyTaxScheme: PeppolPartyTaxSchema | undefined): Effect.fn.Return<XmlNode> {
+export const encodePartyTaxScheme = Effect.fn(function* (partyTaxScheme: PeppolPartyTaxScheme | undefined): Effect.fn.Return<XmlNode> {
   if (Predicate.isNullish(partyTaxScheme)) return undefined;
 
   return { 'cbc:CompanyID': partyTaxScheme.companyId, 'cac:TaxScheme': yield* encodeSimpleIdentifier(partyTaxScheme.taxSchemeId) };

package/src/decoders/fields/encode-tax-representative-party.ts

@@ -1,13 +1,13 @@
 import { Effect, Predicate } from 'effect';
 
 import type { XmlNode } from '#/helpers/get-prop.ts';
-import type { PeppolTaxRepresentativeParty } from '#/schemas/fields/peppol-tax-representative-schema.ts';
+import type { PeppolTaxRepresentative } from '#/schemas/fields/peppol-tax-representative-schema.ts';
 
 import { encodeAddress } from '#/decoders/fields/encode-address.ts';
 import { encodePartyTaxScheme } from '#/decoders/fields/encode-party-tax-scheme.ts';
 
 export const encodeTaxRepresentativeParty = Effect.fn(function* (
-  taxRepresentativeParty: PeppolTaxRepresentativeParty | undefined
+  taxRepresentativeParty: PeppolTaxRepresentative | undefined
 ): Effect.fn.Return<XmlNode> {
   if (Predicate.isNullish(taxRepresentativeParty)) {
     return undefined;

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,26 +74,39 @@ 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({
-    /**
-     * @description An identifier for an object on which the invoice is based (with DocumentTypeCode=130), given by the Seller, the identifier for the supporting
-     * document or the project reference identifier (DocumentTypeCode=50).
-     *
-     * @summary Invoiced object identifier, Supporting document reference or project reference
-     *
-     * @name `#text`
-     */
-    id: Schema.String,
-    /**
-     * @description The identification scheme identifier of the Invoiced object identifier.
-     *
-     * @summary Scheme identifier
-     *
-     * @name `@schemeID`
-     */
-    schemeId: Schema.optional(additionalDocumentReferenceCodeSchema),
-  })
+  PeppolIdentifier.pipe(
+    Schema.fieldsAssign({
+      /**
+       * @description An identifier for an object on which the invoice is based (with DocumentTypeCode=130), given by the Seller, the identifier for the supporting
+       * document or the project reference identifier (DocumentTypeCode=50).
+       *
+       * @summary Invoiced object identifier, Supporting document reference or project reference
+       *
+       * @name `#text`
+       */
+      id: Schema.String,
+      /**
+       * @description The identification scheme identifier of the Invoiced object identifier.
+       *
+       * @summary Scheme identifier
+       *
+       * @name `@schemeID`
+       */
+      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`