@endevops/peppol-schema 0.1.3 → 0.1.5

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,17 @@ export class PeppolInvoiceResponseStatusReasonCodeAction extends opaque<PeppolIn
   })
 ) {}
 
-export const peppolInvoiceResponseStatusReasonCodeSchema = Schema.Union([
+/**
+ * @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 Schema.Union([
   PeppolInvoiceResponseStatusReasonCodeAction,
   PeppolInvoiceResponseStatusReasonCodeReason,
-]);
-
-export type PeppolInvoiceResponseStatusReasonCode = typeof peppolInvoiceResponseStatusReasonCodeSchema.Type;
+]) {}

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);
 }

package/src/schemas/utils/peppol-base-64-schema.ts

@@ -25,9 +25,12 @@ const BASE64_RE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=
 /**
  * @description RFC 4648 base64 string (PEM / MIME / XML line endings tolerated). Effect port of `base64Schema` (`z.string().check(z.refine(...))`): strips CRLF /
  * LF line endings before testing the quantum regex.
+ *
+ * @example
+ *   ```ts
+ *   const value = 'SGVsbG8=';
+ *   ```;
  */
-export const peppolBase64Schema = Schema.String.check(Schema.makeFilter((val: string) => BASE64_RE.test(val.replace(/\r?\n/g, '')))).annotate({
+export class PeppolBase64 extends Schema.String.check(Schema.makeFilter((val: string) => BASE64_RE.test(val.replace(/\r?\n/g, '')))).annotate({
   message: 'Invalid base64',
-});
-
-export type Base64 = typeof peppolBase64Schema.Type;
+}) {}

package/src/schemas/utils/peppol-vat-regex-schema.ts

@@ -1,6 +1,7 @@
 import { Schema } from 'effect';
 
 import { isValidMod97_0208 } from '#/peppol-validations/is-valid-mod97-0208.ts';
+import { opaque } from '#/schemas/utils/opaque.ts';
 
 /**
  * @description Belgian VAT number (`BE` + 10 digits with mod 97-0208 check digits). Effect port of the `BE` member of `vatRegexSchema`: prefix, exact length,
@@ -16,34 +17,41 @@ const belgianVat = Schema.String.check(
 /**
  * @description EU VAT identification number (one member per member-state prefix/pattern). Effect port of `vatRegexSchema` (`z.union([...])` of
  * `z.string().check(...)` members): each member keeps its original prefix + pattern checks as `Schema.String.check` filters.
+ *
+ * @example
+ *   ```ts
+ *   const value = 'DE123456789';
+ *   ```;
  */
-export const peppolVatRegexSchema = Schema.Union([
-  belgianVat,
-  Schema.String.check(Schema.isStartsWith('AT'), Schema.isPattern(/^ATU\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('BG'), Schema.isPattern(/^BG\d{9,10}$/)),
-  Schema.String.check(Schema.isStartsWith('CY'), Schema.isPattern(/^CY\d{8}L$/)),
-  Schema.String.check(Schema.isStartsWith('CZ'), Schema.isPattern(/^CZ\d{8,10}$/)),
-  Schema.String.check(Schema.isStartsWith('DE'), Schema.isPattern(/^DE\d{9}$/)),
-  Schema.String.check(Schema.isStartsWith('DK'), Schema.isPattern(/^DK\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('EE'), Schema.isPattern(/^EE\d{9}$/)),
-  Schema.String.check(Schema.isStartsWith('EL'), Schema.isPattern(/^EL\d{9}$/)),
-  Schema.String.check(Schema.isStartsWith('GR'), Schema.isPattern(/^GR\d{9}$/)),
-  Schema.String.check(Schema.isStartsWith('ES'), Schema.isPattern(/^ES[0-9A-Z]\d{7}[0-9A-Z]$/)),
-  Schema.String.check(Schema.isStartsWith('FI'), Schema.isPattern(/^FI\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('FR'), Schema.isPattern(/^FR[0-9A-Z]{2}\d{9}$/)),
-  Schema.String.check(Schema.isStartsWith('GB'), Schema.isPattern(/^GB(\d{9}(\d{3})?|[A-Z]{2}\d{3})$/)),
-  Schema.String.check(Schema.isStartsWith('HU'), Schema.isPattern(/^HU\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('IE'), Schema.isPattern(/^IE\dS\d{5}L$/)),
-  Schema.String.check(Schema.isStartsWith('IT'), Schema.isPattern(/^IT\d{11}$/)),
-  Schema.String.check(Schema.isStartsWith('LT'), Schema.isPattern(/^LT(\d{9}|\d{12})$/)),
-  Schema.String.check(Schema.isStartsWith('LU'), Schema.isPattern(/^LU\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('LV'), Schema.isPattern(/^LV\d{11}$/)),
-  Schema.String.check(Schema.isStartsWith('MT'), Schema.isPattern(/^MT\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('NL'), Schema.isPattern(/^NL\d{9}B\d{2}$/)),
-  Schema.String.check(Schema.isStartsWith('PL'), Schema.isPattern(/^PL\d{10}$/)),
-  Schema.String.check(Schema.isStartsWith('PT'), Schema.isPattern(/^PT\d{9}$/)),
-  Schema.String.check(Schema.isStartsWith('RO'), Schema.isPattern(/^RO\d{2,10}$/)),
-  Schema.String.check(Schema.isStartsWith('SE'), Schema.isPattern(/^SE\d{12}$/)),
-  Schema.String.check(Schema.isStartsWith('SI'), Schema.isPattern(/^SI\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('SK'), Schema.isPattern(/^SK\d{10}$/)),
-]);
+export class PeppolVatRegex extends opaque<PeppolVatRegex>()(
+  Schema.Union([
+    belgianVat,
+    Schema.String.check(Schema.isStartsWith('AT'), Schema.isPattern(/^ATU\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('BG'), Schema.isPattern(/^BG\d{9,10}$/)),
+    Schema.String.check(Schema.isStartsWith('CY'), Schema.isPattern(/^CY\d{8}L$/)),
+    Schema.String.check(Schema.isStartsWith('CZ'), Schema.isPattern(/^CZ\d{8,10}$/)),
+    Schema.String.check(Schema.isStartsWith('DE'), Schema.isPattern(/^DE\d{9}$/)),
+    Schema.String.check(Schema.isStartsWith('DK'), Schema.isPattern(/^DK\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('EE'), Schema.isPattern(/^EE\d{9}$/)),
+    Schema.String.check(Schema.isStartsWith('EL'), Schema.isPattern(/^EL\d{9}$/)),
+    Schema.String.check(Schema.isStartsWith('GR'), Schema.isPattern(/^GR\d{9}$/)),
+    Schema.String.check(Schema.isStartsWith('ES'), Schema.isPattern(/^ES[0-9A-Z]\d{7}[0-9A-Z]$/)),
+    Schema.String.check(Schema.isStartsWith('FI'), Schema.isPattern(/^FI\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('FR'), Schema.isPattern(/^FR[0-9A-Z]{2}\d{9}$/)),
+    Schema.String.check(Schema.isStartsWith('GB'), Schema.isPattern(/^GB(\d{9}(\d{3})?|[A-Z]{2}\d{3})$/)),
+    Schema.String.check(Schema.isStartsWith('HU'), Schema.isPattern(/^HU\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('IE'), Schema.isPattern(/^IE\dS\d{5}L$/)),
+    Schema.String.check(Schema.isStartsWith('IT'), Schema.isPattern(/^IT\d{11}$/)),
+    Schema.String.check(Schema.isStartsWith('LT'), Schema.isPattern(/^LT(\d{9}|\d{12})$/)),
+    Schema.String.check(Schema.isStartsWith('LU'), Schema.isPattern(/^LU\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('LV'), Schema.isPattern(/^LV\d{11}$/)),
+    Schema.String.check(Schema.isStartsWith('MT'), Schema.isPattern(/^MT\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('NL'), Schema.isPattern(/^NL\d{9}B\d{2}$/)),
+    Schema.String.check(Schema.isStartsWith('PL'), Schema.isPattern(/^PL\d{10}$/)),
+    Schema.String.check(Schema.isStartsWith('PT'), Schema.isPattern(/^PT\d{9}$/)),
+    Schema.String.check(Schema.isStartsWith('RO'), Schema.isPattern(/^RO\d{2,10}$/)),
+    Schema.String.check(Schema.isStartsWith('SE'), Schema.isPattern(/^SE\d{12}$/)),
+    Schema.String.check(Schema.isStartsWith('SI'), Schema.isPattern(/^SI\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('SK'), Schema.isPattern(/^SK\d{10}$/)),
+  ])
+) {}

package/src/schemas/utils/peppol-xsd-time-schema.ts

@@ -17,9 +17,14 @@ const numberFromString = (value: string | undefined): number => {
 /**
  * @description Parse a timezone offset from a string. The string must be in the format `(+|-)HH:MM` where `HH` and `MM` are two digits.
  *
- * @param tz - The timzeone offset string.
+ * @example
+ *   ```ts
+ *   parseZoneOffsetFromString('+01:00'); // a +01:00 zone offset
+ *   ```;
  *
- * @returns
+ * @param tz - The timezone offset string.
+ *
+ * @returns A `DateTime.Zone` offset built from the parsed hours and minutes, or `undefined` when `tz` does not match the offset pattern.
  *
  * @internal
  */
@@ -36,6 +41,11 @@ export const parseZoneOffsetFromString = (tz: `+${number}:${number}` | `-${numbe
 /**
  * @description XSD `time` lexical value (`HH:MM:SS` with optional fractional seconds and timezone). Effect port of `xsdTime` (`z.string().check(z.regex(...))`):
  * keeps the value as a plain string and only validates the shape.
+ *
+ * @example
+ *   ```ts
+ *   const value = '12:30:45+01:00';
+ *   ```;
  */
 export class PeppolXsdTime extends opaque<PeppolXsdTime>()(
   Schema.String.check(

package/src/schemas/utils/quantity-unit-code-to-intl-unit.ts

@@ -1,5 +1,8 @@
 import type { PeppolQuantityUnitCode } from '#/schemas/values/quantity-unit-codes-schema.ts';
 
+/**
+ * @description String union of `Intl.NumberFormat` unit identifiers for base units such as length, area, volume, mass, and temperature.
+ */
 export type BaseIntlUnit =
   | 'acre'
   | 'bit'
@@ -36,10 +39,26 @@ export type BaseIntlUnit =
   | 'terabit'
   | 'terabyte'
   | 'yard';
+/**
+ * @description String union of `Intl.NumberFormat` unit identifiers for time units, used on their own and as the denominator of a rate.
+ */
 export type TimeIntlUnit = 'nanosecond' | 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';
 
+/**
+ * @description Any `Intl.NumberFormat` unit identifier supported by this module: a {@link BaseIntlUnit}, a {@link TimeIntlUnit}, or a rate such as
+ * `'kilometer-per-hour'`.
+ */
 export type IntlUnit = BaseIntlUnit | TimeIntlUnit | `${BaseIntlUnit}-per-${TimeIntlUnit}`;
 
+/**
+ * @description Maps UN/ECE Rec 20 quantity unit codes to `Intl.NumberFormat` unit identifiers. Unmapped codes are omitted.
+ *
+ * @example
+ *   ```ts
+ *   quantityToIntlUnitMap.KGM; // 'kilogram'
+ *   quantityToIntlUnitMap.KMH; // 'kilometer-per-hour'
+ *   ```;
+ */
 export const quantityToIntlUnitMap = {
   CMT: 'centimeter',
   MTR: 'meter',
@@ -106,6 +125,21 @@ export const quantityToIntlUnitMap = {
   '4M': 'gram-per-hour' as IntlUnit,
 } satisfies Partial<Record<string, IntlUnit>>;
 
+/**
+ * @description Looks up the `Intl.NumberFormat` unit identifier for a UN/ECE Rec 20 quantity unit code.
+ *
+ * @example
+ *   ```ts
+ *   quantityUnitCodeToIntlUnit('KGM'); // 'kilogram'
+ *   quantityUnitCodeToIntlUnit('EA'); // undefined
+ *   ```;
+ *
+ * @param code - A quantity unit code, typed as {@link PeppolQuantityUnitCode} but accepting any string.
+ *
+ * @returns The matching {@link IntlUnit}, or `undefined` when the code has no `Intl` unit mapping.
+ *
+ * @see {@link quantityToIntlUnitMap}
+ */
 export function quantityUnitCodeToIntlUnit(code: PeppolQuantityUnitCode | (string & {})): IntlUnit | undefined {
   return (quantityToIntlUnitMap as Record<string, IntlUnit>)[code];
 }

package/src/schemas/values/additional-document-reference-code-schema.ts

@@ -1,25 +1,19 @@
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { additionalDocumentReferenceCodesKeys } from '#/values/additional-document-reference-codes.generated';
 
 /**
- * @description Additional document reference.
+ * @description An additional document reference code from the PEPPOL subset of UNCL 1153 (invoiced object identifier scheme).
  *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL1153/
- * @see {@link additionalDocumentReferenceCodesKeys}
- */
-export type PeppolAdditionalDocumentReferenceCode = typeof additionalDocumentReferenceCodeSchema.Type;
-
-/**
- * @description Validates an additional document reference code against the PEPPOL subset of UNCL 1153 (reference qualifiers).
- *
- * @param error - The custom error message to use when validation fails. Defaults to the generic message.
- *
- * @returns An Effect schema that accepts only valid additional document reference codes.
+ * @example
+ *   ```ts
+ *   'AAA';
+ *   ```;
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL1153/
  * @see {@link additionalDocumentReferenceCodesKeys}
  */
-export const additionalDocumentReferenceCodeSchema = Schema.Literals(additionalDocumentReferenceCodesKeys).pipe(
-  Schema.brand('PeppolAdditionalDocumentReferenceCode')
-);
+export class PeppolAdditionalDocumentReferenceCode extends opaque<PeppolAdditionalDocumentReferenceCode>()(
+  Schema.Literals(additionalDocumentReferenceCodesKeys).pipe(Schema.brand('PeppolAdditionalDocumentReferenceCode'))
+) {}

package/src/schemas/values/allowance-charge-reason-code-schema.ts

@@ -1,26 +1,24 @@
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { allowanceChargeReasonCodesKeys } from '#/values/allowance-charge-reason-codes.generated';
 
 /**
- * @description An allowance or charge reason code as defined by the PEPPOL subset of UNCL 5189.
+ * @description An allowance or charge reason code from the PEPPOL subset of UNCL 5189 (D.16B).
  *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL5189/
- */
-export type PeppolAllowanceChargeReasonCode = typeof allowanceChargeReasonCodeSchema.Type;
-
-/**
- * @description Validates an allowance or charge reason code against the PEPPOL subset of UNCL 5189 (D.16B).
- *
- * @param error - The custom error message to use when validation fails.
- *
- * @returns An Effect schema that accepts only valid allowance/charge reason codes.
+ * @example
+ *   ```ts
+ *   '41';
+ *   ```;
  *
  * @validations
  * - PEPPOL-EN16931-CL002: Document allowance reason code MUST be according to the subset of UNCL 5189 D.16B.
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL5189/
+ * @see {@link allowanceChargeReasonCodesKeys}
  */
-export const allowanceChargeReasonCodeSchema = Schema.Literals(allowanceChargeReasonCodesKeys)
-  .pipe(Schema.brand('PeppolAllowanceChargeReasonCode'))
-  .annotate({ documentation: 'PEPPOL-EN16931-CL002: Reason code MUST be according to subset of UNCL 5189 D.16B.' });
+export class PeppolAllowanceChargeReasonCode extends opaque<PeppolAllowanceChargeReasonCode>()(
+  Schema.Literals(allowanceChargeReasonCodesKeys)
+    .pipe(Schema.brand('PeppolAllowanceChargeReasonCode'))
+    .annotate({ documentation: 'PEPPOL-EN16931-CL002: Reason code MUST be according to subset of UNCL 5189 D.16B.' })
+) {}

package/src/schemas/values/application-response-type-code-schema.ts

@@ -1,23 +1,19 @@
 import { Schema } from 'effect';
 
-import type { ApplicationResponseTypeCodesKeys } from '#/values/application-response-type-codes.generated';
-
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { applicationResponseTypeCodesKeys } from '#/values/application-response-type-codes.generated';
 
 /**
- * @description An application response type code as defined by the PEPPOL subset of UNCL 4343.
- *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL4343/
- */
-export type PeppolApplicationResponseTypeCode = ApplicationResponseTypeCodesKeys;
-
-/**
- * @description Validates an application response type code against the PEPPOL subset of UNCL 4343.
- *
- * @param error - The custom error message to use when validation fails.
+ * @description An application response type code from the PEPPOL subset of UNCL 4343.
  *
- * @returns An Effect schema that accepts only valid application response type codes.
+ * @example
+ *   ```ts
+ *   'AB';
+ *   ```;
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL4343/
+ * @see {@link applicationResponseTypeCodesKeys}
  */
-export const applicationResponseTypeCodeSchema = Schema.Literals(applicationResponseTypeCodesKeys);
+export class PeppolApplicationResponseTypeCode extends opaque<PeppolApplicationResponseTypeCode>()(
+  Schema.Literals(applicationResponseTypeCodesKeys)
+) {}

package/src/schemas/values/charge-reason-code-schema.ts

@@ -1,26 +1,24 @@
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { chargeReasonCodesKeys } from '#/values/charge-reason-codes.generated';
 
 /**
- * @description A charge reason code as defined by the PEPPOL subset of UNCL 7161.
+ * @description A charge reason code from the PEPPOL subset of UNCL 7161 (D.16B).
  *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL7161/
- */
-export type PeppolChargeReasonCode = typeof chargeReasonCodeSchema.Type;
-
-/**
- * @description Validates a charge reason code against the PEPPOL subset of UNCL 7161 (D.16B).
- *
- * @param error - The custom error message to use when validation fails.
- *
- * @returns An Effect schema that accepts only valid charge reason codes.
+ * @example
+ *   ```ts
+ *   'AA';
+ *   ```;
  *
  * @validations
  * - PEPPOL-EN16931-CL003: Charge reason code MUST be according to UNCL 7161 D.16B.
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL7161/
+ * @see {@link chargeReasonCodesKeys}
  */
-export const chargeReasonCodeSchema = Schema.Literals(chargeReasonCodesKeys)
-  .pipe(Schema.brand('PeppolChargeReasonCode'))
-  .annotate({ documentation: 'PEPPOL-EN16931-CL003: Reason code MUST be according to UNCL 7161 D.16B.' });
+export class PeppolChargeReasonCode extends opaque<PeppolChargeReasonCode>()(
+  Schema.Literals(chargeReasonCodesKeys)
+    .pipe(Schema.brand('PeppolChargeReasonCode'))
+    .annotate({ documentation: 'PEPPOL-EN16931-CL003: Reason code MUST be according to UNCL 7161 D.16B.' })
+) {}