@endevops/peppol-schema 0.1.2 → 0.1.4

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

@@ -22,6 +22,7 @@ import { PeppolCreditNote } from '#/schemas/peppol-credit-note-schema.ts';
 import { PeppolInvoiceResponse } from '#/schemas/peppol-invoice-response-schema.ts';
 import { PeppolInvoice } from '#/schemas/peppol-invoice-schema.ts';
 import { PeppolMessageLevelResponse } from '#/schemas/peppol-message-level-response-schema.ts';
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { builderOptions } from '#/xml/builder-options.ts';
 import { parseXmlNodable } from '#/xml/nodable-parser.ts';
 
@@ -37,9 +38,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);
 
 /**
@@ -94,17 +135,35 @@ 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(
-  Schema.encodeTo(Schema.String, {
-    encode: SchemaGetter.transformEffect((value, options) => encodeDocumentXml(value, options)),
-    decode: SchemaGetter.transformEffect((value, options) => decodeDocumentXml(value, options)),
-  })
-);
+export class PeppolDocumentSchema extends opaque<PeppolDocumentSchema>()(
+  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 +173,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,21 @@ export class PeppolInvoiceResponseDocumentActualResponseWithStatus extends opaqu
   })
 ) {}
 
-export const peppolInvoiceResponseDocumentActualResponseSchema = Schema.Union([
-  PeppolInvoiceResponseDocumentActualResponseWithStatus,
-  PeppolInvoiceResponseDocumentActualResponseWithoutStatus,
-]);
+/**
+ * @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 opaque<PeppolInvoiceResponseDocumentActualResponse>()(
+  Schema.Union([PeppolInvoiceResponseDocumentActualResponseWithStatus, PeppolInvoiceResponseDocumentActualResponseWithoutStatus])
+) {}
 
-export type InvoiceResponseDocumentActualResponse = typeof peppolInvoiceResponseDocumentActualResponseSchema.Type;
+/**
+ * @description Alias of {@link PeppolInvoiceResponseDocumentActualResponse}.
+ */
+export type InvoiceResponseDocumentActualResponse = PeppolInvoiceResponseDocumentActualResponse;

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.
      *
@@ -60,4 +80,7 @@ export class PeppolInvoiceResponseDocumentActualResponseStatus extends opaque<Pe
   })
 ) {}
 
+/**
+ * @description Alias of {@link PeppolInvoiceResponseDocumentActualResponseStatus}.
+ */
 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,21 @@ export class PeppolInvoiceResponseDocumentResponseParty extends opaque<PeppolInv
   })
 ) {}
 
+/**
+ * @description Alias of {@link PeppolInvoiceResponseDocumentResponseParty}.
+ */
 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 +145,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 +168,7 @@ export class PeppolInvoiceResponseDocumentResponse extends opaque<PeppolInvoiceR
      *
      * @cardinality (1..1)
      */
-    response: peppolInvoiceResponseDocumentActualResponseSchema,
+    response: PeppolInvoiceResponseDocumentActualResponse,
     /**
      * @summary Document reference
      *

package/src/schemas/peppol-invoice-response-status-reason-code-schema.ts

@@ -1,12 +1,22 @@
 import { Schema } from 'effect';
 
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { opStatusActionSchema } from '#/schemas/values/op-status-action-schema.ts';
-import { opStatusReasonSchema } from '#/schemas/values/op-status-reason-schema.ts';
+import { PeppolOpStatusAction } from '#/schemas/values/op-status-action-schema.ts';
+import { PeppolOpStatusReason } from '#/schemas/values/op-status-reason-schema.ts';
 
+/**
+ * @description Status clarification reason (`cbc:StatusReasonCode` with `@listId="OPStatusReason"`), a value from the OPStatusReason code list.
+ *
+ * @example
+ *   ```ts
+ *   { value: 'REF', listId: 'OPStatusReason' }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponseStatusReasonCode}
+ */
 export class PeppolInvoiceResponseStatusReasonCodeReason extends opaque<PeppolInvoiceResponseStatusReasonCodeReason>()(
   Schema.Struct({
-    value: opStatusReasonSchema,
+    value: PeppolOpStatusReason,
     /**
      * @description List identifier for clarification.
      *
@@ -18,9 +28,19 @@ export class PeppolInvoiceResponseStatusReasonCodeReason extends opaque<PeppolIn
   })
 ) {}
 
+/**
+ * @description Status clarification action (`cbc:StatusReasonCode` with `@listId="OPStatusAction"`), a value from the OPStatusAction code list.
+ *
+ * @example
+ *   ```ts
+ *   { value: 'PIN', listId: 'OPStatusAction' }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponseStatusReasonCode}
+ */
 export class PeppolInvoiceResponseStatusReasonCodeAction extends opaque<PeppolInvoiceResponseStatusReasonCodeAction>()(
   Schema.Struct({
-    value: opStatusActionSchema,
+    value: PeppolOpStatusAction,
     /**
      * @description List identifier for clarification.
      *
@@ -32,9 +52,16 @@ export class PeppolInvoiceResponseStatusReasonCodeAction extends opaque<PeppolIn
   })
 ) {}
 
-export const peppolInvoiceResponseStatusReasonCodeSchema = Schema.Union([
-  PeppolInvoiceResponseStatusReasonCodeAction,
-  PeppolInvoiceResponseStatusReasonCodeReason,
-]);
-
-export type PeppolInvoiceResponseStatusReasonCode = typeof peppolInvoiceResponseStatusReasonCodeSchema.Type;
+/**
+ * @description Union of the accepted status clarification reasons and actions on an invoice response.
+ *
+ * @example
+ *   ```ts
+ *   { value: 'REF', listId: 'OPStatusReason' }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponseDocumentActualResponseStatus}
+ */
+export class PeppolInvoiceResponseStatusReasonCode extends opaque<PeppolInvoiceResponseStatusReasonCode>()(
+  Schema.Union([PeppolInvoiceResponseStatusReasonCodeAction, PeppolInvoiceResponseStatusReasonCodeReason])
+) {}

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

@@ -4,10 +4,38 @@ import { PeppolInvoiceLine } from '#/schemas/fields/peppol-invoice-line-schema.t
 import { PeppolBillingBase } from '#/schemas/peppol-billing-base-schema.ts';
 import { PeppolIsoDateString } from '#/schemas/peppol-iso-date-string.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { invoiceTypeCodeSchema } from '#/schemas/values/invoice-type-code-schema.ts';
+import { PeppolInvoiceTypeCode } from '#/schemas/values/invoice-type-code-schema.ts';
 
+/**
+ * @description Wraps the `cac:ProjectReference` element on an invoice: an identifier of the project the invoice relates to.
+ *
+ * @example
+ *   ```ts
+ *   { id: 'project-123' }
+ *   ```;
+ *
+ * @see {@link PeppolInvoice}
+ */
 export class PeppolProjectReference extends opaque<PeppolProjectReference>()(Schema.Struct({ id: Schema.String })) {}
 
+/**
+ * @description UBL `Invoice` for PEPPOL BIS Billing 3.0. Extends {@link PeppolBillingBase} with the due date, type code, lines and project reference.
+ *
+ * @example
+ *   ```ts
+ *   {
+ *     customizationId: 'urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0',
+ *     profileId: 'urn:fdc:peppol.eu:2017:poacc:billing:01:1.0',
+ *     id: '33445566',
+ *     issueDate: '2017-11-01',
+ *     documentCurrencyCode: 'EUR',
+ *     invoiceTypeCode: '380'
+ *   }
+ *   ```;
+ *
+ * @see {@link PeppolBillingBase}
+ * @see {@link PeppolCreditNote}
+ */
 export class PeppolInvoice extends opaque<PeppolInvoice>()(
   Schema.Struct({
     ...PeppolBillingBase.fields,
@@ -34,7 +62,7 @@ export class PeppolInvoice extends opaque<PeppolInvoice>()(
      *
      * @name cbc:InvoiceTypeCode
      */
-    invoiceTypeCode: invoiceTypeCodeSchema,
+    invoiceTypeCode: PeppolInvoiceTypeCode,
     /**
      * @summary PROJECT REFERENCE
      *

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

@@ -5,6 +5,16 @@ import { PeppolDocumentResponseDocument } from '#/schemas/peppol-document-respon
 import { PeppolDocumentResponseLineResponse } from '#/schemas/peppol-document-response-line-response-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
+/**
+ * @description Wraps `cac:DocumentResponse` inside a message level response: the response, the document reference and any per-line responses.
+ *
+ * @example
+ *   ```ts
+ *   { response: { responseCode: 'RE' }, documentReference: { id: 'EnvelopeID-12345' }, lineResponse: [] }
+ *   ```;
+ *
+ * @see {@link PeppolMessageLevelResponse}
+ */
 export class PeppolMessageLevelResponseDocumentResponse extends opaque<PeppolMessageLevelResponseDocumentResponse>()(
   Schema.Struct({
     /**

package/src/schemas/peppol-message-level-response-party-schema.ts

@@ -3,6 +3,16 @@ import { Schema } from 'effect';
 import { PeppolIdentifier } from '#/schemas/fields/peppol-identifier-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
+/**
+ * @description Party used as `cac:SenderParty` or `cac:ReceiverParty` on a message level response, holding the party's electronic address.
+ *
+ * @example
+ *   ```ts
+ *   { endpointId: { id: '7300010000001', schemeId: '0088' } }
+ *   ```;
+ *
+ * @see {@link PeppolMessageLevelResponse}
+ */
 export class PeppolMessageLevelResponseParty extends opaque<PeppolMessageLevelResponseParty>()(
   Schema.Struct({
     /**

package/src/schemas/peppol-message-level-response-schema.ts

@@ -7,6 +7,24 @@ import { PeppolMessageLevelResponseParty } from '#/schemas/peppol-message-level-
 import { opaque } from '#/schemas/utils/opaque.ts';
 import { PeppolXsdTime } from '#/schemas/utils/peppol-xsd-time-schema.ts';
 
+/**
+ * @description UBL `ApplicationResponse` message level response for PEPPOL BIS Billing 3.0 (profile `urn:fdc:peppol.eu:poacc:bis:mlr:3`).
+ *
+ * @example
+ *   ```ts
+ *   {
+ *     customizationId: 'urn:fdc:peppol.eu:poacc:trns:mlr:3',
+ *     profileId: 'urn:fdc:peppol.eu:poacc:bis:mlr:3',
+ *     id: '23',
+ *     issueDate: '2017-11-01',
+ *     senderParty: {},
+ *     receiverParty: {},
+ *     documentResponse: { response: { responseCode: 'RE' }, documentReference: { id: 'EnvelopeID-12345' }, lineResponse: [] }
+ *   }
+ *   ```;
+ *
+ * @see {@link PeppolInvoiceResponse}
+ */
 export class PeppolMessageLevelResponse extends opaque<PeppolMessageLevelResponse>()(
   Schema.Struct({
     /**

package/src/schemas/utils/format-quantity-with-unit.ts

@@ -1,6 +1,25 @@
 import { quantityToIntlUnitMap } from '#/schemas/utils/quantity-unit-code-to-intl-unit.ts';
 import { quantityUnitCodes } from '#/values/quantity-unit-codes.generated';
 
+/**
+ * @description Formats a quantity and its unit code for a locale. Uses `Intl.NumberFormat` for mapped codes, otherwise the code list name.
+ *
+ * @example
+ *   ```ts
+ *   formatQuantityWithUnit(5, 'KGM', 'en-US', 'long'); // '5 kilograms'
+ *   formatQuantityWithUnit(10, 'EA'); // '10 each'
+ *   ```;
+ *
+ * @param value - The numeric quantity to format.
+ * @param code - The UN/ECE Rec 20 unit code to render, for example `KGM` or `MTR`.
+ * @param locale - BCP 47 locale tag passed to `Intl.NumberFormat`. Defaults to `'en-US'`.
+ * @param unitDisplay - `Intl` unit display style: `'short'`, `'narrow'`, or `'long'`. Defaults to `'short'`.
+ *
+ * @returns The formatted quantity and unit, for example `'5 kilograms'`. Falls back to `<number> <name>` when the code has no `Intl` unit or `Intl`
+ *   rejects the unit.
+ *
+ * @see {@link quantityUnitCodeToIntlUnit}
+ */
 export function formatQuantityWithUnit(
   value: number,
   code: string,

package/src/schemas/utils/get-credit-note-type-code-description.ts

@@ -2,6 +2,18 @@ import type { PeppolCreditNoteTypeCode } from '#/schemas/values/credit-note-type
 
 import { creditNoteTypeCodes } from '#/values/credit-notes-type-codes.generated';
 
+/**
+ * @description Returns the human-readable description of a PEPPOL credit note type code (UNCL1001 subset).
+ *
+ * @example
+ *   ```ts
+ *   getCreditNoteTypeCodeDescription('381'); // 'Credit note'
+ *   ```;
+ *
+ * @param code - A valid {@link PeppolCreditNoteTypeCode}, for example `'381'`.
+ *
+ * @returns The description registered for the code, for example `'Credit note'`.
+ */
 export function getCreditNoteTypeCodeDescription(code: PeppolCreditNoteTypeCode): string {
   return (creditNoteTypeCodes as Record<string, string>)[code] as string;
 }

package/src/schemas/utils/get-invoice-type-code-description.ts

@@ -2,6 +2,18 @@ import type { PeppolInvoiceTypeCode } from '#/schemas/values/invoice-type-code-s
 
 import { invoiceTypeCodes } from '#/values/invoice-type-codes.generated';
 
+/**
+ * @description Returns the human-readable description of a PEPPOL invoice type code (UNCL1001 subset).
+ *
+ * @example
+ *   ```ts
+ *   getInvoiceTypeCodeDescription('380'); // 'Commercial invoice'
+ *   ```;
+ *
+ * @param code - A valid {@link PeppolInvoiceTypeCode}, for example `'380'`.
+ *
+ * @returns The description registered for the code, for example `'Commercial invoice'`.
+ */
 export function getInvoiceTypeCodeDescription(code: PeppolInvoiceTypeCode): string {
   return (invoiceTypeCodes as Record<string, string>)[code] as string;
 }

package/src/schemas/utils/is-valid-credit-note-type-code.ts

@@ -2,6 +2,19 @@ import type { PeppolCreditNoteTypeCode } from '#/schemas/values/credit-note-type
 
 import { creditNoteTypeCodes } from '#/values/credit-notes-type-codes.generated';
 
+/**
+ * @description Type guard for PEPPOL credit note type codes (UNCL1001 subset).
+ *
+ * @example
+ *   ```ts
+ *   isValidCreditNoteTypeCode('381'); // true
+ *   isValidCreditNoteTypeCode('UNKNOWN'); // false
+ *   ```;
+ *
+ * @param code - The string to test.
+ *
+ * @returns `true` when `code` is a known credit note type code, narrowing it to {@link PeppolCreditNoteTypeCode}; otherwise `false`.
+ */
 export function isValidCreditNoteTypeCode(code: string): code is PeppolCreditNoteTypeCode {
   return code in creditNoteTypeCodes;
 }

package/src/schemas/utils/is-valid-invoice-type-code.ts

@@ -2,6 +2,19 @@ import type { PeppolInvoiceTypeCode } from '#/schemas/values/invoice-type-code-s
 
 import { invoiceTypeCodes } from '#/values/invoice-type-codes.generated';
 
+/**
+ * @description Type guard for PEPPOL invoice type codes (UNCL1001 subset).
+ *
+ * @example
+ *   ```ts
+ *   isValidInvoiceTypeCode('380'); // true
+ *   isValidInvoiceTypeCode('UNKNOWN'); // false
+ *   ```;
+ *
+ * @param code - The string to test.
+ *
+ * @returns `true` when `code` is a known invoice type code, narrowing it to {@link PeppolInvoiceTypeCode}; otherwise `false`.
+ */
 export function isValidInvoiceTypeCode(code: string): code is PeppolInvoiceTypeCode {
   return code in invoiceTypeCodes;
 }

package/src/schemas/utils/is-valid-process.ts

@@ -2,6 +2,19 @@ import type { PeppolProcesses } from '#/schemas/values/peppol-process-schema.ts'
 
 import { processesList } from '#/values/processes.generated';
 
+/**
+ * @description Type guard for PEPPOL business process identifiers of the form `<scheme>::<value>`.
+ *
+ * @example
+ *   ```ts
+ *   isValidProcess('cenbii-procid-ubl::urn:fdc:peppol.eu:2017:poacc:billing:01:1.0'); // true
+ *   isValidProcess('cenbii-procid-ubl::urn:not:a:process'); // false
+ *   ```;
+ *
+ * @param code - The process identifier to test.
+ *
+ * @returns `true` when `code` appears in {@link processesList}, narrowing it to {@link PeppolProcesses}; otherwise `false`.
+ */
 export function isValidProcess(code: string): code is PeppolProcesses {
   return processesList.includes(code);
 }