@endevops/peppol-schema 0.1.3 → 0.1.5

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

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

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

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

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

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

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

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

package/src/schemas/fields/peppol-binary-object-schema.ts

@@ -1,14 +1,22 @@
 import { Schema } from 'effect';
 
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { peppolBase64Schema } from '#/schemas/utils/peppol-base-64-schema.ts';
-import { mimeCodesSchema } from '#/schemas/values/mime-codes-schema.ts';
+import { PeppolBase64 } from '#/schemas/utils/peppol-base-64-schema.ts';
+import { PeppolMimeCode } from '#/schemas/values/mime-codes-schema.ts';
 
 // RFC 4648 §5 — Base64url Encoding: URL/file-safe alphabet (A-Z a-z 0-9 - _), optional `=` padding.
 // Effect port of `z.base64url()`: keeps the value as a plain string and only validates the shape.
 const base64UrlSchema = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9\-_]+={0,2}$/)).annotate({ message: 'Invalid base64url' });
 
 /**
+ * @description An attached document embedded in the Invoice as a Base64 encoded binary object, together with its MIME type and file name. Wraps the
+ * `cbc:EmbeddedDocumentBinaryObject` element.
+ *
+ * @example
+ *   ```ts
+ *   { content: 'aHR0cHM6Ly90ZXN0LXZlZmEuZGlmaS5uby9wZXBwb2xiaXM=', mimeCode: 'text/csv', filename: 'Hours - spent.csv' }
+ *   ```;
+ *
  * @summary Binary object for attachments
  *
  * @name cbc:EmbeddedDocumentBinaryObject (+ @mimeCode, @filename)
@@ -25,7 +33,7 @@ export class PeppolBinaryObject extends opaque<PeppolBinaryObject>()(
      *
      * @name `#text` (Base64 content)
      */
-    content: Schema.Union([peppolBase64Schema, base64UrlSchema]),
+    content: Schema.Union([PeppolBase64, base64UrlSchema]),
     /**
      * @description The mime code of the attached document.
      *
@@ -36,7 +44,7 @@ export class PeppolBinaryObject extends opaque<PeppolBinaryObject>()(
      *
      * @name `@mimeCode`
      */
-    mimeCode: mimeCodesSchema,
+    mimeCode: PeppolMimeCode,
     /**
      * @description The file name of the attached document.
      *

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

@@ -2,6 +2,17 @@ import { Schema } from 'effect';
 
 import { opaque } from '#/schemas/utils/opaque.ts';
 
+/**
+ * @description A contact point for a party, such as the person responsible for receiving the Invoice. Wraps the `cac:Contact` element with an optional name,
+ * telephone number and electronic mail address.
+ *
+ * @example
+ *   ```ts
+ *   { name: 'Lisa Johnson', telephone: '23434234', electronicMail: 'lj@buyer.se' }
+ *   ```;
+ *
+ * @see {@link PeppolPartySchema}
+ */
 export class PeppolContact extends opaque<PeppolContact>()(
   Schema.Struct({
     /**

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

@@ -3,7 +3,7 @@ import { Schema } from 'effect';
 import { PeppolBaseLine } from '#/schemas/fields/peppol-base-line-schema.ts';
 import { PeppolQuantity } from '#/schemas/fields/peppol-quantity-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { quantityUnitCodesSchema } from '#/schemas/values/quantity-unit-codes-schema.ts';
+import { PeppolQuantityUnitCode } from '#/schemas/values/quantity-unit-codes-schema.ts';
 
 /**
  * @description Credit note line is identical to Invoice line except the quantity element name.
@@ -35,10 +35,15 @@ export class PeppolCreditNoteLine extends opaque<PeppolCreditNoteLine>()(
            *
            * @see {@link quantityUnitCodes}
            */
-          unitCode: quantityUnitCodesSchema,
+          unitCode: PeppolQuantityUnitCode,
         })
       ),
     })
   )
 ) {}
+/**
+ * @description Encoded form of {@link PeppolCreditNoteLine} produced by the Effect Schema codec. Fields mirror the decoded structure.
+ *
+ * @see {@link PeppolCreditNoteLine}
+ */
 export interface PeppolCreditNoteLineEncoded extends Schema.Codec.Encoded<typeof PeppolCreditNoteLine> {}

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

@@ -2,11 +2,21 @@ import { Schema } from 'effect';
 
 import { PeppolIsoDateString } from '#/schemas/peppol-iso-date-string.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { icdCodesSchema } from '#/schemas/values/icd-codes-schema.ts';
+import { PeppolIcdCode } from '#/schemas/values/icd-codes-schema.ts';
 
 import { PeppolAddress } from './peppol-address-schema.ts';
 import { PeppolIdentifier } from './peppol-identifier-schema.ts';
 
+/**
+ * @description The name of the party to which the goods and services are delivered. Wraps the `cac:PartyName` element of the delivery party.
+ *
+ * @example
+ *   ```ts
+ *   { name: 'Delivery party Name' }
+ *   ```;
+ *
+ * @see {@link PeppolDeliveryParty}
+ */
 export class PeppolDeliveryPartyPartyName extends opaque<PeppolDeliveryPartyPartyName>()(
   Schema.Struct({
     /**
@@ -20,6 +30,16 @@ export class PeppolDeliveryPartyPartyName extends opaque<PeppolDeliveryPartyPart
   })
 ) {}
 
+/**
+ * @description The party to which the goods and services are delivered, when it differs from the Buyer. Wraps the `cac:DeliveryParty` element.
+ *
+ * @example
+ *   ```ts
+ *   { partyName: { name: 'Delivery party Name' } }
+ *   ```;
+ *
+ * @see {@link PeppolDelivery}
+ */
 export class PeppolDeliveryParty extends opaque<PeppolDeliveryParty>()(
   Schema.Struct({
     /**
@@ -31,6 +51,17 @@ export class PeppolDeliveryParty extends opaque<PeppolDeliveryParty>()(
   })
 ) {}
 
+/**
+ * @description The location at which the goods and services are delivered, identified by an identifier and an optional address. Wraps the `cac:DeliveryLocation`
+ * element.
+ *
+ * @example
+ *   ```ts
+ *   { id: { id: '9483759475923478', schemeId: '0088' }, address: { cityName: 'Stockholm', countryCode: { identificationCode: 'SE' } } }
+ *   ```;
+ *
+ * @see {@link PeppolDelivery}
+ */
 export class PeppolDeliveryLocation extends opaque<PeppolDeliveryLocation>()(
   Schema.Struct({
     /**
@@ -64,7 +95,7 @@ export class PeppolDeliveryLocation extends opaque<PeppolDeliveryLocation>()(
            *
            * @name `@schemeID`
            */
-          schemeId: Schema.optional(icdCodesSchema),
+          schemeId: Schema.optional(PeppolIcdCode),
         })
       )
     ),
@@ -79,6 +110,17 @@ export class PeppolDeliveryLocation extends opaque<PeppolDeliveryLocation>()(
   })
 ) {}
 
+/**
+ * @description Information about the delivery of the goods and services, such as the actual delivery date, the delivery location and the delivery party. Wraps the
+ * `cac:Delivery` element.
+ *
+ * @example
+ *   ```ts
+ *   { actualDeliveryDate: '2017-11-01', deliveryLocation: { id: { id: '9483759475923478' } } }
+ *   ```;
+ *
+ * @see {@link PeppolDeliveryLocation}
+ */
 export class PeppolDelivery extends opaque<PeppolDelivery>()(
   Schema.Struct({
     /**

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

@@ -3,6 +3,14 @@ import { Schema } from 'effect';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
 /**
+ * @description A generic identifier paired with an optional identification scheme identifier. Wraps a `cbc:ID` element and its optional `@schemeID` attribute, and
+ * is reused across document references.
+ *
+ * @example
+ *   ```ts
+ *   { id: '99887766', schemeId: '0088' }
+ *   ```;
+ *
  * @summary Identifier with optional scheme
  *
  * @name `cbc:ID (+ optional @schemeID)`

package/src/schemas/fields/peppol-invoice-line-period-schema.ts

@@ -3,6 +3,17 @@ import { Schema } from 'effect';
 import { PeppolIsoDateString } from '#/schemas/peppol-iso-date-string.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
+/**
+ * @description The period relevant for an Invoice line, given by an optional start date and end date. Wraps the `cac:InvoicePeriod` element as used on a line; the
+ * document level period extends this shape in {@link PeppolInvoicePeriod}.
+ *
+ * @example
+ *   ```ts
+ *   { startDate: '2017-10-01', endDate: '2017-10-31' }
+ *   ```;
+ *
+ * @see {@link PeppolInvoicePeriod}
+ */
 export class PeppolInvoiceLinePeriod extends opaque<PeppolInvoiceLinePeriod>()(
   Schema.Struct({
     /**

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

@@ -3,9 +3,11 @@ import { Schema } from 'effect';
 import { PeppolBaseLine } from '#/schemas/fields/peppol-base-line-schema.ts';
 import { PeppolQuantity } from '#/schemas/fields/peppol-quantity-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { quantityUnitCodesSchema } from '#/schemas/values/quantity-unit-codes-schema.ts';
+import { PeppolQuantityUnitCode } from '#/schemas/values/quantity-unit-codes-schema.ts';
 
 /**
+ * @description A line of the Invoice, extending the common line fields with the invoiced quantity. Wraps the `cac:InvoiceLine` element.
+ *
  * @summary Invoice line
  *
  * @name cac:InvoiceLine
@@ -38,9 +40,14 @@ export class PeppolInvoiceLine extends opaque<PeppolInvoiceLine>()(
          *
          * @see {@link quantityUnitCodes}
          */
-        unitCode: quantityUnitCodesSchema,
+        unitCode: PeppolQuantityUnitCode,
       })
     ),
   })
 ) {}
+/**
+ * @description Encoded form of {@link PeppolInvoiceLine} produced by the Effect Schema codec. Fields mirror the decoded structure.
+ *
+ * @see {@link PeppolInvoiceLine}
+ */
 export interface PeppolInvoiceLineEncoded extends Schema.Codec.Encoded<typeof PeppolInvoiceLine> {}

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

@@ -2,7 +2,7 @@ import { Schema } from 'effect';
 
 import { PeppolInvoiceLinePeriod } from '#/schemas/fields/peppol-invoice-line-period-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { vatDateCodeSchema } from '#/schemas/values/vat-date-code-schema.ts';
+import { PeppolVatDateCode } from '#/schemas/values/vat-date-code-schema.ts';
 
 /**
  * @description A group of business terms providing information on the invoice period. Also called delivery period. If the group is used, the invoiceing period
@@ -25,7 +25,7 @@ export class PeppolInvoicePeriod extends opaque<PeppolInvoicePeriod>()(
        *
        * @name `cbc:DescriptionCode`
        */
-      descriptionCode: Schema.optional(vatDateCodeSchema),
+      descriptionCode: Schema.optional(PeppolVatDateCode),
     })
   )
 ) {}

package/src/schemas/fields/peppol-item-classification-schema.ts

@@ -1,7 +1,7 @@
 import { Schema } from 'effect';
 
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { itemClassificationCodesSchema } from '#/schemas/values/item-classification-codes-schema.ts';
+import { PeppolItemClassificationCode } from '#/schemas/values/item-classification-codes-schema.ts';
 
 /**
  * @description A code for classifying the item by its type or nature.
@@ -30,7 +30,7 @@ export class PeppolItemClassification extends opaque<PeppolItemClassification>()
      *
      * @name `@listID`
      */
-    listId: itemClassificationCodesSchema,
+    listId: PeppolItemClassificationCode,
     /**
      * @description The identification scheme version identifier of the Item classification identifier.
      *

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

@@ -2,9 +2,20 @@ import { Schema } from 'effect';
 
 import { PriceAllowanceCharge } from '#/schemas/fields/peppol-line-price-allowance-charge-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { allowanceChargeReasonCodeSchema } from '#/schemas/values/allowance-charge-reason-code-schema.ts';
-import { chargeReasonCodeSchema } from '#/schemas/values/charge-reason-code-schema.ts';
+import { PeppolAllowanceChargeReasonCode } from '#/schemas/values/allowance-charge-reason-code-schema.ts';
+import { PeppolChargeReasonCode } from '#/schemas/values/charge-reason-code-schema.ts';
 
+/**
+ * @description Shared fields for an allowance or charge applied to an Invoice line. Extends the price level allowance and charge fields with the reason text and
+ * the multiplier factor used to calculate the amount.
+ *
+ * @example
+ *   ```ts
+ *   { amount: { value: 200, currencyId: 'EUR' }, chargeIndicator: false, allowanceChargeReason: 'Discount' }
+ *   ```;
+ *
+ * @see {@link PeppolLineAllowanceCharge}
+ */
 export class BaseLineAllowanceCharge extends opaque<BaseLineAllowanceCharge>()(
   Schema.Struct({
     ...PriceAllowanceCharge.fields /**
@@ -24,13 +35,24 @@ export class BaseLineAllowanceCharge extends opaque<BaseLineAllowanceCharge>()(
   })
 ) {}
 
+/**
+ * @description An allowance applied to an Invoice line, marked by a `cbc:ChargeIndicator` of `false`. Adds an allowance reason code to the shared line allowance
+ * and charge fields.
+ *
+ * @example
+ *   ```ts
+ *   { amount: { value: 200, currencyId: 'EUR' }, chargeIndicator: false, allowanceChargeReasonCode: '95' }
+ *   ```;
+ *
+ * @see {@link PeppolLineAllowanceCharge}
+ */
 export class PeppolLineAllowance extends opaque<PeppolLineAllowance>()(
   Schema.Struct({
     ...BaseLineAllowanceCharge.fields,
     /**
      * @name cbc:AllowanceChargeReasonCode
      */
-    allowanceChargeReasonCode: Schema.optional(allowanceChargeReasonCodeSchema),
+    allowanceChargeReasonCode: Schema.optional(PeppolAllowanceChargeReasonCode),
     /**
      * @name cbc:ChargeIndicator
      *
@@ -42,13 +64,24 @@ export class PeppolLineAllowance extends opaque<PeppolLineAllowance>()(
   })
 ) {}
 
+/**
+ * @description A charge applied to an Invoice line, marked by a `cbc:ChargeIndicator` of `true`. Adds a charge reason code to the shared line allowance and charge
+ * fields.
+ *
+ * @example
+ *   ```ts
+ *   { amount: { value: 25, currencyId: 'EUR' }, chargeIndicator: true, allowanceChargeReasonCode: 'AA' }
+ *   ```;
+ *
+ * @see {@link PeppolLineAllowanceCharge}
+ */
 export class PeppolLineCharge extends opaque<PeppolLineCharge>()(
   Schema.Struct({
     ...BaseLineAllowanceCharge.fields,
     /**
      * @name cbc:AllowanceChargeReasonCode
      */
-    allowanceChargeReasonCode: Schema.optional(chargeReasonCodeSchema),
+    allowanceChargeReasonCode: Schema.optional(PeppolChargeReasonCode),
     /**
      * @name cbc:ChargeIndicator
      *
@@ -60,9 +93,24 @@ export class PeppolLineCharge extends opaque<PeppolLineCharge>()(
   })
 ) {}
 
-export const peppolLineAllowanceChargeSchema = Schema.Union([PeppolLineAllowance, PeppolLineCharge]).annotate({
+/**
+ * @description An allowance or charge applied to an Invoice line, selected by the `cbc:ChargeIndicator` value: `false` selects an allowance, `true` selects a
+ * charge.
+ *
+ * @example
+ *   ```ts
+ *   { amount: { value: 25, currencyId: 'EUR' }, chargeIndicator: true, allowanceChargeReasonCode: 'AA', allowanceChargeReason: 'Advertising' }
+ *   ```;
+ *
+ * @see {@link PeppolLineAllowance}
+ */
+export class PeppolLineAllowanceCharge extends Schema.Union([PeppolLineAllowance, PeppolLineCharge]).annotate({
   message: 'unable to decode line allowance charge',
-});
+}) {}
 
-export type PeppolLineAllowanceCharge = typeof peppolLineAllowanceChargeSchema.Type;
-export type PeppolLineAllowanceChargeEncoded = typeof peppolLineAllowanceChargeSchema.Encoded;
+/**
+ * @description Encoded form of {@link PeppolLineAllowanceCharge} produced by the Effect Schema codec.
+ *
+ * @see {@link PeppolLineAllowanceCharge}
+ */
+export type PeppolLineAllowanceChargeEncoded = Schema.Codec.Encoded<typeof PeppolLineAllowanceCharge>;