@endevops/peppol-schema 0.1.3 → 0.1.5

package/src/schemas/peppol-billing-base-schema.ts

@@ -3,7 +3,7 @@ import { Effect, Schema } from 'effect';
 import { DEFAULT_CUSTOMIZATION_ID } from '#/schemas/fields/default-customization-id.ts';
 import { DEFAULT_PROFILE_ID } from '#/schemas/fields/default-profile-id.ts';
 import { PeppolAdditionalDocumentReference } from '#/schemas/fields/peppol-additional-document-reference-schema.ts';
-import { peppolAllowanceChargeSchema } from '#/schemas/fields/peppol-allowance-charge-schema.ts';
+import { PeppolAllowanceCharge } from '#/schemas/fields/peppol-allowance-charge-schema.ts';
 import { PeppolBillingReference } from '#/schemas/fields/peppol-billing-reference-schema.ts';
 import { PeppolDelivery } from '#/schemas/fields/peppol-delivery-schema.ts';
 import { PeppolInvoicePeriod } from '#/schemas/fields/peppol-invoice-period-schema.ts';
@@ -14,11 +14,21 @@ import { PeppolPayeeParty } from '#/schemas/fields/peppol-payee-party-schema.ts'
 import { PeppolPaymentMeans } from '#/schemas/fields/peppol-payment-means-schema.ts';
 import { PeppolPaymentTerms } from '#/schemas/fields/peppol-payment-terms-schema.ts';
 import { PeppolTaxRepresentative } from '#/schemas/fields/peppol-tax-representative-schema.ts';
-import { PeppolTaxTotalsBase } from '#/schemas/fields/peppol-tax-totals-base-schema.ts';
+import { PeppolTaxTotal } from '#/schemas/fields/peppol-tax-totals-base-schema.ts';
 import { PeppolIsoDateString } from '#/schemas/peppol-iso-date-string.ts';
 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 Wraps the `cac:ContractDocumentReference` element: an identifier of a contract that the billing document references.
+ *
+ * @example
+ *   ```ts
+ *   { id: '123Contractref' }
+ *   ```;
+ *
+ * @see {@link PeppolBillingBase}
+ */
 export class PeppolContractDocumentReference extends opaque<PeppolContractDocumentReference>()(
   Schema.Struct({
     /**
@@ -35,6 +45,16 @@ export class PeppolContractDocumentReference extends opaque<PeppolContractDocume
   })
 ) {}
 
+/**
+ * @description Wraps the `cac:OriginatorDocumentReference` element: the identification of the call for tender or lot the invoice relates to.
+ *
+ * @example
+ *   ```ts
+ *   { id: 'PPID-123' }
+ *   ```;
+ *
+ * @see {@link PeppolBillingBase}
+ */
 export class PeppolOriginatorDocumentReference extends opaque<PeppolOriginatorDocumentReference>()(
   Schema.Struct({
     /**
@@ -51,6 +71,16 @@ export class PeppolOriginatorDocumentReference extends opaque<PeppolOriginatorDo
   })
 ) {}
 
+/**
+ * @description Wraps the `cac:ReceiptDocumentReference` element: an identifier of a referenced receiving advice.
+ *
+ * @example
+ *   ```ts
+ *   { id: 'rec98' }
+ *   ```;
+ *
+ * @see {@link PeppolBillingBase}
+ */
 export class PeppolReceiptDocumentReference extends opaque<PeppolReceiptDocumentReference>()(
   Schema.Struct({
     /**
@@ -67,6 +97,16 @@ export class PeppolReceiptDocumentReference extends opaque<PeppolReceiptDocument
   })
 ) {}
 
+/**
+ * @description Wraps the `cac:DespatchDocumentReference` element: an identifier of a referenced despatch advice.
+ *
+ * @example
+ *   ```ts
+ *   { id: 'desp98' }
+ *   ```;
+ *
+ * @see {@link PeppolBillingBase}
+ */
 export class PeppolDespatchDocumentReference extends opaque<PeppolDespatchDocumentReference>()(
   Schema.Struct({
     /**
@@ -86,8 +126,8 @@ export class PeppolDespatchDocumentReference extends opaque<PeppolDespatchDocume
 /**
  * @description Base schema for a billing document.
  *
- * @see {@link creditNoteSchema} - the credit note schema
- * @see {@link invoiceSchema} - the invoice schema
+ * @see {@link PeppolCreditNote} - the credit note schema
+ * @see {@link PeppolInvoice} - the invoice schema
  */
 export class PeppolBillingBase extends opaque<PeppolBillingBase>()(
   Schema.Struct({
@@ -182,7 +222,7 @@ export class PeppolBillingBase extends opaque<PeppolBillingBase>()(
      *
      * @name `cbc:DocumentCurrencyCode`
      */
-    documentCurrencyCode: currencyCodeSchema,
+    documentCurrencyCode: PeppolCurrencyCode,
     /**
      * @description The currency used for VAT accounting and reporting purposes as accepted or required in the country of the Seller. Shall be used in combination
      * with the Invoice total VAT amount in accounting currency (BT-111), when the VAT accounting currency code differs from the Invoice currency
@@ -195,7 +235,7 @@ export class PeppolBillingBase extends opaque<PeppolBillingBase>()(
      *
      * @name `cbc:TaxCurrencyCode`
      */
-    taxCurrencyCode: Schema.optional(currencyCodeSchema),
+    taxCurrencyCode: Schema.optional(PeppolCurrencyCode),
     /**
      * @description A textual value that specifies where to book the relevant data into the Buyer's financial accounts.
      *
@@ -345,7 +385,7 @@ export class PeppolBillingBase extends opaque<PeppolBillingBase>()(
      *
      * @name cac:AllowanceCharge
      */
-    allowanceCharges: Schema.optional(Schema.Array(peppolAllowanceChargeSchema)),
+    allowanceCharges: Schema.optional(Schema.Array(PeppolAllowanceCharge)),
 
     /**
      * @description When tax currency code is provided, two instances of the tax total must be present, but only one with tax subtotal.
@@ -354,7 +394,7 @@ export class PeppolBillingBase extends opaque<PeppolBillingBase>()(
      *
      * @name cac:TaxTotal
      */
-    taxTotals: Schema.Array(PeppolTaxTotalsBase).check(Schema.isMinLength(1), Schema.isMaxLength(2)),
+    taxTotals: Schema.Array(PeppolTaxTotal).check(Schema.isMinLength(1), Schema.isMaxLength(2)),
 
     /**
      * @summary DOCUMENT TOTALS

package/src/schemas/peppol-credit-note-schema.ts

@@ -3,7 +3,7 @@ import { Schema } from 'effect';
 import { PeppolCreditNoteLine } from '#/schemas/fields/peppol-credit-note-line-schema.ts';
 import { PeppolBillingBase } from '#/schemas/peppol-billing-base-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { creditNoteTypeCodeSchema } from '#/schemas/values/credit-note-type-code-schema.ts';
+import { PeppolCreditNoteTypeCode } from '#/schemas/values/credit-note-type-code-schema.ts';
 
 /**
  * @description Main UBL Credit Note schema (camelCase properties) Effect port of `creditNoteSchema` (`z.extend(billingBaseSchema, ...)` →
@@ -26,6 +26,6 @@ export class PeppolCreditNote extends opaque<PeppolCreditNote>()(
      *
      * @name cbc:CreditNoteTypeCode
      */
-    creditNoteTypeCode: creditNoteTypeCodeSchema,
+    creditNoteTypeCode: PeppolCreditNoteTypeCode,
   })
 ) {}

package/src/schemas/peppol-document-response-document-reference-schema.ts

@@ -1,8 +1,18 @@
 import { Schema } from 'effect';
 
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { peppolDocumentTypeCodeSchema } from '#/schemas/values/peppol-document-type-code-schema.ts';
+import { PeppolDocumentTypeCode } from '#/schemas/values/peppol-document-type-code-schema.ts';
 
+/**
+ * @description Wraps `cac:DocumentReference` inside a message level response: identifies the business document the response is based on.
+ *
+ * @example
+ *   ```ts
+ *   { id: 'EnvelopeID-12345', versionId: '2' }
+ *   ```;
+ *
+ * @see {@link PeppolMessageLevelResponseDocumentResponse}
+ */
 export class PeppolDocumentResponseDocumentReference extends opaque<PeppolDocumentResponseDocumentReference>()(
   Schema.Struct({
     /**
@@ -23,7 +33,7 @@ export class PeppolDocumentResponseDocumentReference extends opaque<PeppolDocume
      *
      * @name `cbc:DocumentTypeCode`
      */
-    documentTypeCode: Schema.optional(peppolDocumentTypeCodeSchema),
+    documentTypeCode: Schema.optional(PeppolDocumentTypeCode),
     /**
      * @description The version of the document that has been identifier with the document identifier.
      *
@@ -37,5 +47,3 @@ export class PeppolDocumentResponseDocumentReference extends opaque<PeppolDocume
     versionId: Schema.optional(Schema.String),
   })
 ) {}
-
-export type PeppolMessageLevelDocumentResponseDocumentReference = PeppolDocumentResponseDocumentReference;

package/src/schemas/peppol-document-response-document-schema.ts

@@ -1,16 +1,18 @@
 import { Schema } from 'effect';
 
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { applicationResponseTypeCodeSchema } from '#/schemas/values/application-response-type-code-schema.ts';
+import { PeppolApplicationResponseTypeCode } from '#/schemas/values/application-response-type-code-schema.ts';
 
 /**
+ * @description Wraps `cac:Response` inside a message level response: the overall response code and an optional textual note.
+ *
  * @summary Response information
  *
  * @name `cac:Response`
  *
  * @cardinality (1..1)
  *
- * @see {@link messageLevelResponseDocumentResponseSchema}
+ * @see {@link PeppolMessageLevelResponseDocumentResponse}
  */
 export class PeppolDocumentResponseDocument extends opaque<PeppolDocumentResponseDocument>()(
   Schema.Struct({
@@ -25,7 +27,7 @@ export class PeppolDocumentResponseDocument extends opaque<PeppolDocumentRespons
      *
      * @name `cbc:ResponseCode`
      */
-    responseCode: applicationResponseTypeCodeSchema,
+    responseCode: PeppolApplicationResponseTypeCode,
     /**
      * @description Used to meake any comments or instructions relevant to the response. The use of this element requires manual assessment by the receiver.
      *
@@ -34,5 +36,3 @@ export class PeppolDocumentResponseDocument extends opaque<PeppolDocumentRespons
     description: Schema.optional(Schema.String),
   })
 ) {}
-
-export type PeppolMessageLevelResponseDocumentResponseDocument = PeppolDocumentResponseDocument;

package/src/schemas/peppol-document-response-line-response-content-schema.ts

@@ -1,8 +1,18 @@
 import { Schema } from 'effect';
 
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { applicationResponseTypeCodeSchema } from '#/schemas/values/application-response-type-code-schema.ts';
+import { PeppolApplicationResponseTypeCode } from '#/schemas/values/application-response-type-code-schema.ts';
 
+/**
+ * @description Wraps `cac:Status` inside a line response: the coded reason for an issue found in the document.
+ *
+ * @example
+ *   ```ts
+ *   { statusReasonCode: 'SV' }
+ *   ```;
+ *
+ * @see {@link PeppolDocumentResponseLineResponseContent}
+ */
 export class PeppolStatus extends opaque<PeppolStatus>()(
   Schema.Struct({
     /**
@@ -16,6 +26,16 @@ export class PeppolStatus extends opaque<PeppolStatus>()(
   })
 ) {}
 
+/**
+ * @description A response to a particular line in the business document: the line response code, a description of the issue and its coded status.
+ *
+ * @example
+ *   ```ts
+ *   { responseCode: 'RE', description: 'Validation gives error [CL-T77-R0002]', status: { statusReasonCode: 'SV' } }
+ *   ```;
+ *
+ * @see {@link PeppolDocumentResponseLineResponse}
+ */
 export class PeppolDocumentResponseLineResponseContent extends opaque<PeppolDocumentResponseLineResponseContent>()(
   Schema.Struct({
     /**
@@ -29,7 +49,7 @@ export class PeppolDocumentResponseLineResponseContent extends opaque<PeppolDocu
      *
      * @name `cbc:ResponseCode`
      */
-    responseCode: applicationResponseTypeCodeSchema,
+    responseCode: PeppolApplicationResponseTypeCode,
     /**
      * @description The description of the issued identifier in the transaction document.
      *

package/src/schemas/peppol-document-response-line-response-schema.ts

@@ -3,6 +3,16 @@ import { Schema } from 'effect';
 import { PeppolDocumentResponseLineResponseContent } from '#/schemas/peppol-document-response-line-response-content-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
+/**
+ * @description Wraps `cac:LineReference` inside a line response: an XPath pointing at the element that caused the reported issue.
+ *
+ * @example
+ *   ```ts
+ *   { lineId: '/Invoice/cac:InvoiceLine[1]' }
+ *   ```;
+ *
+ * @see {@link PeppolDocumentResponseLineResponse}
+ */
 export class PeppolLineReference extends opaque<PeppolLineReference>()(
   Schema.Struct({
     /**
@@ -20,6 +30,19 @@ export class PeppolLineReference extends opaque<PeppolLineReference>()(
   })
 ) {}
 
+/**
+ * @description Wraps `cac:LineResponse` inside a message level response: pairs a line reference with the response for that line.
+ *
+ * @example
+ *   ```ts
+ *   {
+ *     lineReference: { lineId: '/Invoice/cac:InvoiceLine[1]' },
+ *     response: { responseCode: 'RE', description: 'Invalid tax category', status: { statusReasonCode: 'SV' } }
+ *   }
+ *   ```;
+ *
+ * @see {@link PeppolMessageLevelResponseDocumentResponse}
+ */
 export class PeppolDocumentResponseLineResponse extends opaque<PeppolDocumentResponseLineResponse>()(
   Schema.Struct({
     /**
@@ -36,5 +59,3 @@ export class PeppolDocumentResponseLineResponse extends opaque<PeppolDocumentRes
     response: PeppolDocumentResponseLineResponseContent,
   })
 ) {}
-
-export type PeppolMessageLevelDocumentResponseLineResponse = PeppolDocumentResponseLineResponse;

package/src/schemas/peppol-document-schema.ts

@@ -37,9 +37,49 @@ type PeppolDocumentObject = typeof peppolDocumentObjectSchema.Encoded;
 
 const parseXml = (value: string): XmlNode => parseXmlNodable(value);
 
+/**
+ * @description Type guard that returns `true` when a decoded value is a {@link PeppolInvoice}.
+ *
+ * @example
+ *   ```ts
+ *   isPeppolInvoice(doc); // true for a UBL Invoice
+ *   ```;
+ *
+ * @see {@link PeppolDocumentSchema}
+ */
 export const isPeppolInvoice = Schema.is(PeppolInvoice);
+/**
+ * @description Type guard that returns `true` when a decoded value is a {@link PeppolCreditNote}.
+ *
+ * @example
+ *   ```ts
+ *   isPeppolCreditNote(doc); // true for a UBL CreditNote
+ *   ```;
+ *
+ * @see {@link PeppolDocumentSchema}
+ */
 export const isPeppolCreditNote = Schema.is(PeppolCreditNote);
+/**
+ * @description Type guard that returns `true` when a decoded value is a {@link PeppolMessageLevelResponse}.
+ *
+ * @example
+ *   ```ts
+ *   isPeppolMessageLevelResponse(doc); // true for an MLR ApplicationResponse
+ *   ```;
+ *
+ * @see {@link PeppolDocumentSchema}
+ */
 export const isPeppolMessageLevelResponse = Schema.is(PeppolMessageLevelResponse);
+/**
+ * @description Type guard that returns `true` when a decoded value is a {@link PeppolInvoiceResponse}.
+ *
+ * @example
+ *   ```ts
+ *   isPeppolInvoiceResponse(doc); // true for an invoice response ApplicationResponse
+ *   ```;
+ *
+ * @see {@link PeppolDocumentSchema}
+ */
 export const isPeppolInvoiceResponse = Schema.is(PeppolInvoiceResponse);
 
 /**
@@ -85,7 +125,8 @@ const encodeDocumentXml = Effect.fn('encode-peppol-document-xml')(function* (val
   } else {
     const rootNodes = Object.keys(value);
     return yield* Effect.fail(
-      new SchemaIssue.InvalidValue({ message: `Unsupported document type: ${value.profileId}\n${rootNodes.join(',')}` }, value, options)
+      // oxlint-disable-next-line typescript/no-explicit-any this is safe since it is only for logging purposes
+      new SchemaIssue.InvalidValue({ message: `Unsupported document type: ${(value as any)?.profileId}\n${rootNodes.join(',')}` }, value, options)
     );
   }
 
@@ -94,17 +135,33 @@ const encodeDocumentXml = Effect.fn('encode-peppol-document-xml')(function* (val
 
 /**
  * @description Union of every supported PEPPOL business document. Members discriminate cleanly: invoice vs credit note via `invoiceLines`/`creditNoteLines`,
- * message-level vs invoice response via the `profileId` literal.
+ * message-level vs invoice response via the `profileId` literal. Decodes and encodes XML strings by dispatching on the root element;
+ * `ApplicationResponse` is split on `cbc:ProfileID`.
+ *
+ * @example
+ *   ```ts
+ *   const doc = Schema.decodeUnknownSync(PeppolDocumentSchema)(xml); // decoded document union
+ *   ```;
+ *
+ * @see {@link PeppolDocumentDecoded}
+ * @see {@link PeppolDocumentEncoded}
  */
-export const peppolDocumentSchema = peppolDocumentObjectSchema.pipe(
+export class PeppolDocumentSchema extends peppolDocumentObjectSchema.pipe(
   Schema.encodeTo(Schema.String, {
     encode: SchemaGetter.transformEffect((value, options) => encodeDocumentXml(value, options)),
     decode: SchemaGetter.transformEffect((value, options) => decodeDocumentXml(value, options)),
   })
-);
+) {}
 
-export type PeppolDocumentEncoded = Schema.Codec.Encoded<typeof peppolDocumentSchema>;
-export type PeppolDocumentDecoded = Schema.Schema.Type<typeof peppolDocumentSchema>;
+/**
+ * @description Encoded form of {@link PeppolDocumentSchema}: the XML string representation.
+ */
+export type PeppolDocumentEncoded = Schema.Codec.Encoded<typeof PeppolDocumentSchema>;
+
+/**
+ * @description Decoded form of {@link PeppolDocumentSchema}: the union of supported document classes.
+ */
+export type PeppolDocumentDecoded = Schema.Schema.Type<typeof PeppolDocumentSchema>;
 
 /**
  * @description This defines the types of documents that are sent/received through the peppol network.
@@ -114,5 +171,11 @@ export type PeppolDocument = PeppolInvoice | PeppolCreditNote;
  * @description This defines the types of message that are sent/received through the peppol network.
  */
 export type PeppolMessage = PeppolMessageLevelResponse | PeppolInvoiceResponse;
+/**
+ * @description Every document type supported by {@link PeppolDocumentSchema}: the billing documents and the response messages.
+ */
 export type PeppolAllDocuments = PeppolDocument | PeppolMessage;
+/**
+ * @description A line from either a {@link PeppolInvoice} or a {@link PeppolCreditNote}.
+ */
 export type PeppolDocumentLine = PeppolInvoiceLine | PeppolCreditNoteLine;

package/src/schemas/peppol-invoice-response-document-actual-response-schema.ts

@@ -6,9 +6,40 @@ import { PeppolInvoiceResponseDocumentActualResponseStatus } from '#/schemas/pep
 import { PeppolIsoDateString } from '#/schemas/peppol-iso-date-string.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
+/**
+ * @description Response codes that require a clarification in `cac:Status`: `UQ`, `RE` and `CA`.
+ *
+ * @example
+ *   ```ts
+ *   withStatusCodes; // Schema.Literals(['UQ', 'RE', 'CA'])
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponseDocumentActualResponseWithStatus}
+ */
 export const withStatusCodes = Schema.Literals(invoiceResponseCodeNeedsSchema);
+
+/**
+ * @description Response codes that do not require a clarification in `cac:Status`: `AB`, `AP`, `IP` and `PD`.
+ *
+ * @example
+ *   ```ts
+ *   withoutStatusCodes; // Schema.Literals(['AB', 'AP', 'IP', 'PD'])
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponseDocumentActualResponseWithoutStatus}
+ */
 export const withoutStatusCodes = Schema.Literals(invoiceResponseCodeNotNeedsSchema);
 
+/**
+ * @description Invoice response for statuses that do not require a clarification; the `cac:Status` group is optional.
+ *
+ * @example
+ *   ```ts
+ *   { responseCode: 'AP', effectiveDate: '2018-08-02' }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponseDocumentActualResponse}
+ */
 export class PeppolInvoiceResponseDocumentActualResponseWithoutStatus extends opaque<PeppolInvoiceResponseDocumentActualResponseWithoutStatus>()(
   Schema.Struct({
     /**
@@ -40,6 +71,16 @@ export class PeppolInvoiceResponseDocumentActualResponseWithoutStatus extends op
   })
 ) {}
 
+/**
+ * @description Invoice response for statuses that require a clarification; at least one `cac:Status` group is mandatory.
+ *
+ * @example
+ *   ```ts
+ *   { responseCode: 'RE', status: [{ statusReason: 'TAX reference not found' }] }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponseDocumentActualResponse}
+ */
 export class PeppolInvoiceResponseDocumentActualResponseWithStatus extends opaque<PeppolInvoiceResponseDocumentActualResponseWithStatus>()(
   Schema.Struct({
     /**
@@ -74,9 +115,17 @@ export class PeppolInvoiceResponseDocumentActualResponseWithStatus extends opaqu
   })
 ) {}
 
-export const peppolInvoiceResponseDocumentActualResponseSchema = Schema.Union([
+/**
+ * @description Union of the invoice response variants selected by `cbc:ResponseCode`: one that requires a clarification and one that does not.
+ *
+ * @example
+ *   ```ts
+ *   { responseCode: 'AP', effectiveDate: '2018-08-02' }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponseDocumentResponse}
+ */
+export class PeppolInvoiceResponseDocumentActualResponse extends Schema.Union([
   PeppolInvoiceResponseDocumentActualResponseWithStatus,
   PeppolInvoiceResponseDocumentActualResponseWithoutStatus,
-]);
-
-export type InvoiceResponseDocumentActualResponse = typeof peppolInvoiceResponseDocumentActualResponseSchema.Type;
+]) {}

package/src/schemas/peppol-invoice-response-document-actual-response-status-schema.ts

@@ -1,8 +1,18 @@
 import { Schema } from 'effect';
 
-import { peppolInvoiceResponseStatusReasonCodeSchema } from '#/schemas/peppol-invoice-response-status-reason-code-schema.ts';
+import { PeppolInvoiceResponseStatusReasonCode } from '#/schemas/peppol-invoice-response-status-reason-code-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
+/**
+ * @description Wraps `cac:Condition` inside a status: a detail code and its optional value that further explains the clarification.
+ *
+ * @example
+ *   ```ts
+ *   { attributeId: 'BT-75', description: 'EU123456789' }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponseDocumentActualResponseStatus}
+ */
 export class PeppolInvoiceResponseCondition extends opaque<PeppolInvoiceResponseCondition>()(
   Schema.Struct({
     /**
@@ -30,6 +40,16 @@ export class PeppolInvoiceResponseCondition extends opaque<PeppolInvoiceResponse
   })
 ) {}
 
+/**
+ * @description Wraps `cac:Status` inside an invoice response: an optional clarification code and description plus any condition details.
+ *
+ * @example
+ *   ```ts
+ *   { statusReasonCode: { value: 'REF', listId: 'OPStatusReason' }, statusReason: 'TAX reference not found' }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponseDocumentActualResponse}
+ */
 export class PeppolInvoiceResponseDocumentActualResponseStatus extends opaque<PeppolInvoiceResponseDocumentActualResponseStatus>()(
   Schema.Struct({
     /**
@@ -39,7 +59,7 @@ export class PeppolInvoiceResponseDocumentActualResponseStatus extends opaque<Pe
      *
      * @name `cbc:StatusReasonCode`
      */
-    statusReasonCode: Schema.optional(peppolInvoiceResponseStatusReasonCodeSchema),
+    statusReasonCode: Schema.optional(PeppolInvoiceResponseStatusReasonCode),
     /**
      * @description The description of the clarification given for the invoice status.
      *
@@ -59,5 +79,3 @@ export class PeppolInvoiceResponseDocumentActualResponseStatus extends opaque<Pe
     condition: Schema.optional(Schema.Array(PeppolInvoiceResponseCondition)),
   })
 ) {}
-
-export type InvoiceResponseDocumentActualResponseStatus = PeppolInvoiceResponseDocumentActualResponseStatus;

package/src/schemas/peppol-invoice-response-schema.ts

@@ -4,13 +4,23 @@ import { INVOICE_RESPONSE_PROFILE_ID } from '#/constants/invoice-response-profil
 import { PeppolContact } from '#/schemas/fields/peppol-contact-schema.ts';
 import { PeppolIdentifier } from '#/schemas/fields/peppol-identifier-schema.ts';
 import { PeppolPartyLegalEntity } from '#/schemas/fields/peppol-party-legal-entity-schema.ts';
-import { peppolInvoiceResponseDocumentActualResponseSchema } from '#/schemas/peppol-invoice-response-document-actual-response-schema.ts';
+import { PeppolInvoiceResponseDocumentActualResponse } from '#/schemas/peppol-invoice-response-document-actual-response-schema.ts';
 import { PeppolIsoDateString } from '#/schemas/peppol-iso-date-string.ts';
 import { PeppolMessageLevelResponseParty } from '#/schemas/peppol-message-level-response-party-schema.ts';
 import { PeppolMessageLevelResponse } from '#/schemas/peppol-message-level-response-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { peppolDocumentTypeCodeSchema } from '#/schemas/values/peppol-document-type-code-schema.ts';
+import { PeppolDocumentTypeCode } from '#/schemas/values/peppol-document-type-code-schema.ts';
 
+/**
+ * @description Wraps `cac:PartyName` for the seller or buyer on an invoice response: the party's legal or trading name.
+ *
+ * @example
+ *   ```ts
+ *   { name: 'Seller Business Name AS' }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponseDocumentResponseParty}
+ */
 export class PeppolInvoiceResponseDocumentResponsePartyName extends opaque<PeppolInvoiceResponseDocumentResponsePartyName>()(
   Schema.Struct({
     /**
@@ -25,6 +35,16 @@ export class PeppolInvoiceResponseDocumentResponsePartyName extends opaque<Peppo
   })
 ) {}
 
+/**
+ * @description Party used for the sender and receiver of an invoice response. Extends {@link PeppolMessageLevelResponseParty}.
+ *
+ * @example
+ *   ```ts
+ *   { partyLegalEntity: { registrationName: 'Seller Business Name AS' } }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponse}
+ */
 export class PeppolInvoiceResponseParty extends opaque<PeppolInvoiceResponseParty>()(
   PeppolMessageLevelResponseParty.pipe(
     Schema.fieldsAssign({
@@ -37,6 +57,16 @@ export class PeppolInvoiceResponseParty extends opaque<PeppolInvoiceResponsePart
   )
 ) {}
 
+/**
+ * @description Sender party of an invoice response. Extends {@link PeppolInvoiceResponseParty} with optional `cac:Contact` details.
+ *
+ * @example
+ *   ```ts
+ *   { partyLegalEntity: { registrationName: 'Seller Business Name AS' } }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponse}
+ */
 export class PeppolInvoiceResponseSenderParty extends opaque<PeppolInvoiceResponseSenderParty>()(
   PeppolInvoiceResponseParty.pipe(
     Schema.fieldsAssign({
@@ -69,8 +99,16 @@ export class PeppolInvoiceResponseDocumentResponseParty extends opaque<PeppolInv
   })
 ) {}
 
-export type PeppolInvoiceDocumentResponseParty = PeppolInvoiceResponseDocumentResponseParty;
-
+/**
+ * @description Wraps `cac:DocumentReference` inside an invoice response: identifies the invoice the status applies to.
+ *
+ * @example
+ *   ```ts
+ *   { id: 'inv-99876', issueDate: '2018-08-01', documentTypeCode: '380' }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponseDocumentResponse}
+ */
 export class PeppolInvoiceResponseDocumentReference extends opaque<PeppolInvoiceResponseDocumentReference>()(
   Schema.Struct({
     /**
@@ -102,10 +140,20 @@ export class PeppolInvoiceResponseDocumentReference extends opaque<PeppolInvoice
      *
      * @summary Identifier type code
      */
-    documentTypeCode: peppolDocumentTypeCodeSchema,
+    documentTypeCode: PeppolDocumentTypeCode,
   })
 ) {}
 
+/**
+ * @description Wraps `cac:DocumentResponse` inside an invoice response: the response, the referenced invoice and optional parties.
+ *
+ * @example
+ *   ```ts
+ *   { response: { responseCode: 'AP', effectiveDate: '2018-08-02' }, documentReference: { id: 'inv-99876', documentTypeCode: '380' } }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponse}
+ */
 export class PeppolInvoiceResponseDocumentResponse extends opaque<PeppolInvoiceResponseDocumentResponse>()(
   Schema.Struct({
     /**
@@ -115,7 +163,7 @@ export class PeppolInvoiceResponseDocumentResponse extends opaque<PeppolInvoiceR
      *
      * @cardinality (1..1)
      */
-    response: peppolInvoiceResponseDocumentActualResponseSchema,
+    response: PeppolInvoiceResponseDocumentActualResponse,
     /**
      * @summary Document reference
      *