@financica/ubl 0.16.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.17.0
4
+
5
+ ### Changed
6
+
7
+ - **BREAKING: one UBL model for the parser, the serializer and the build helpers.** `UblInvoice` (root export, re-exported from `@financica/ubl/build`) replaces the build-side `UblDocument`, which remains as a deprecated alias for one release. On the parsed model: `UblParty.endpointId`/`endpointSchemeId` → `endpoint: { value, scheme? }`; `companyId: string` + `companyIdSchemeId` → `companyId: { value, scheme? }`; `UblLine.taxPercent`/`taxCategoryId`/`taxSchemeId` → `taxCategory: { id?, percent?, schemeId?, exemptionReason?, exemptionReasonCode? }` (same object on `UblAllowanceCharge`); `UblTaxSubtotal.taxPercent`/`taxCategoryId`/`taxSchemeId`/`taxExemptionReason` → `category` (same shape); the top-level `taxSubtotals` → `taxTotal: { taxAmount?, subtotals }`, where `taxAmount` is BT-110 as the document states it (never summed from the subtotals); `UblLine.baseQuantity` (BT-149) is now read. On the build side: `supplier`/`customer` → `seller`/`buyer`, `vatNumber` → `vatId`, `legalName` → `registrationName`, `priceAmount` → `unitPrice` (the per-unit price; the serializer writes `PriceAmount = unitPrice × baseQuantity`, and `deriveUnitPrice` returns `{ unitPrice, baseQuantity? }`), line `name` → `description` (written as `cbc:Description`, and as `cbc:Name` unless `itemName` is set), attachment `base64` → `base64Content`, `precedingInvoiceId` → `billingReference.invoiceId`, `UblPeriod` → `UblInvoicePeriod`, `documentType: "invoice" | "creditNote"` → `"Invoice" | "CreditNote"`, and every absent output field is an absent key instead of `null` (`buildCompanyId`, `parsePeppolEndpoint`, `resolveVatEndpoint`, `resolveCompanyIdScheme` return `undefined`; `buildSupplierParty`/`buildCustomerParty`/`normalizeAddress` omit absent keys). Caller-input types (`UblSupplier`, `UblCustomer`, `AddressInput`, `CustomerTaxIdInput`) still accept `null`. `buildTaxTotals` throws `UblBuildError` for a line without a `taxCategory`. `normalizeUblResponse` produces the same `InvoiceExtractionDTO`; only the `extra.tax_subtotals` passthrough changes shape (each entry is now `{ taxableAmount?, taxAmount?, category? }`).
8
+ - **BREAKING: `serializeUblDocument` validates and throws `UblBuildError`.** Also exported as `serializeUblInvoice` (the preferred name). Because the model is permissive, the serializer enforces what EN 16931 / Peppol BIS Billing 3.0 make mandatory and throws the new `UblBuildError` (exported from the root and `/build`, `name` set, `readonly cause?`) naming the BT and model path: document `id`, `issueDate`, `currency`, `seller.name`, `buyer.name`, an `endpoint.scheme` on any endpoint, at least one line, per line `quantity`, `unitCode`, `unitPrice`, `lineExtensionAmount`, `taxCategory.id` (and `taxCategory.percent` unless the category is `O`), `taxTotal.taxAmount`, `monetaryTotal.lineExtensionAmount`/`taxExclusiveAmount`/`taxInclusiveAmount`/`payableAmount`, and per VAT subtotal its `taxableAmount`, `taxAmount` and `category`. An attachment needs `filename`, `mimeCode` and `base64Content`; an attachment with only `externalUri` is written as `cac:ExternalReference`. `customizationId`, `profileId` and `invoiceTypeCode` are written when set (defaulting to the BIS values), so a parsed document re-serializes faithfully.
9
+
3
10
  ## 0.16.0
4
11
 
5
12
  ### Changed
package/README.md CHANGED
@@ -5,7 +5,7 @@ TypeScript toolkit for [UBL (Universal Business Language)](https://www.oasis-ope
5
5
  The package is split into two entry points:
6
6
 
7
7
  - `@financica/ubl` — the parse side: read UBL XML into typed objects (`parseUblInvoice`, `normalizeUblResponse`, MLR parsing).
8
- - `@financica/ubl/build` — the build side: assemble a `UblDocument` and serialize it to Peppol BIS Billing 3.0 XML.
8
+ - `@financica/ubl/build` — the build side: assemble a `UblInvoice` (the same model the parser produces) and serialize it to Peppol BIS Billing 3.0 XML.
9
9
 
10
10
  ## Installation
11
11
 
@@ -62,59 +62,55 @@ Handles UTF-8 BOM stripping automatically.
62
62
 
63
63
  ### Build UBL XML
64
64
 
65
- Construct a `UblDocument`, a vendor-neutral mirror of the Peppol BIS Billing 3.0
66
- fields, and serialize it with `serializeUblDocument`.
65
+ Construct a `UblInvoice` — the same model `parseUblInvoice` returns — and
66
+ serialize it with `serializeUblInvoice`. The model is permissive (the parser
67
+ reads whatever a document states); the serializer enforces what EN 16931 /
68
+ Peppol BIS make mandatory and throws `UblBuildError`, naming the field, when
69
+ something is missing.
67
70
 
68
71
  ```typescript
69
- import { serializeUblDocument, type UblDocument } from "@financica/ubl/build";
72
+ import { serializeUblInvoice, type UblInvoice } from "@financica/ubl/build";
70
73
 
71
- const doc: UblDocument = {
72
- documentType: "invoice",
74
+ const doc: UblInvoice = {
75
+ documentType: "Invoice",
73
76
  id: "INV-001",
74
77
  issueDate: "2026-01-15",
75
78
  dueDate: "2026-02-14",
76
- note: null,
77
79
  currency: "EUR",
78
- buyerReference: null,
79
- precedingInvoiceId: null,
80
- supplier: {
80
+ seller: {
81
81
  endpoint: { scheme: "0208", value: "0800279001" },
82
82
  name: "Acme BV",
83
- legalName: "Acme BV",
84
- vatNumber: "BE0800279001",
83
+ registrationName: "Acme BV",
84
+ vatId: "BE0800279001",
85
85
  companyId: { value: "0800279001", scheme: "0208" },
86
86
  address: {
87
87
  street: "Rue de la Loi 1",
88
- additionalStreet: null,
89
88
  city: "Brussels",
90
89
  postalZone: "1000",
91
- countrySubentity: null,
92
90
  countryCode: "BE",
93
91
  },
94
92
  },
95
- customer: {
93
+ buyer: {
96
94
  endpoint: { scheme: "0208", value: "0123456789" },
97
95
  name: "Globex SA",
98
- legalName: "Globex SA",
99
- vatNumber: "BE0123456789",
96
+ registrationName: "Globex SA",
97
+ vatId: "BE0123456789",
100
98
  companyId: { value: "0123456789", scheme: "0208" },
101
99
  address: {
102
100
  street: "Avenue Louise 50",
103
- additionalStreet: null,
104
101
  city: "Brussels",
105
102
  postalZone: "1050",
106
- countrySubentity: null,
107
103
  countryCode: "BE",
108
104
  },
109
105
  },
110
106
  lines: [
111
107
  {
112
108
  id: "1",
113
- name: "Consulting services",
109
+ description: "Consulting services",
114
110
  quantity: 1,
115
111
  unitCode: "C62",
116
112
  lineExtensionAmount: 100,
117
- priceAmount: 100,
113
+ unitPrice: 100,
118
114
  taxCategory: { id: "S", percent: 21 },
119
115
  },
120
116
  ],
@@ -130,14 +126,13 @@ const doc: UblDocument = {
130
126
  taxInclusiveAmount: 121,
131
127
  payableAmount: 121,
132
128
  },
133
- attachments: [],
134
129
  };
135
130
 
136
- const xml = serializeUblDocument(doc);
131
+ const xml = serializeUblInvoice(doc);
137
132
  ```
138
133
 
139
- Set `documentType: "creditNote"` (with `precedingInvoiceId` referencing the
140
- original invoice) to emit a `CreditNote` instead.
134
+ Set `documentType: "CreditNote"` (with `billingReference: { invoiceId }`
135
+ referencing the original invoice) to emit a `CreditNote` instead.
141
136
 
142
137
  For a document that is already paid, pass the settled gross amount as
143
138
  `prepaidAmount` (BT-113) so `payableAmount` (BT-115) reports what is actually
@@ -1,3 +1,4 @@
1
+ import { S as UblBuildError, a as UblBillingReference, b as UblTaxSubtotal, d as UblInvoice, f as UblInvoicePeriod, g as UblParty, h as UblMonetaryTotal, i as UblAttachment, m as UblLine, n as UblAddress, o as UblCompanyId, u as UblEndpoint, x as UblTaxTotal, y as UblTaxCategory } from "../types-DossV2at.js";
1
2
  //#region src/build/ubl/constants.d.ts
2
3
  /** Peppol BIS Billing 3.0 / EN 16931 identifiers and fixed code values. */
3
4
  /** EN 16931 + Peppol BIS Billing 3.0 customization (BT-24). */
@@ -19,178 +20,27 @@ declare const NS_CREDIT_NOTE = "urn:oasis:names:specification:ubl:schema:xsd:Cre
19
20
  declare const NS_CAC = "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2";
20
21
  declare const NS_CBC = "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2";
21
22
  //#endregion
22
- //#region src/build/ubl/types.d.ts
23
+ //#region src/build/ubl/serialize.d.ts
23
24
  /**
24
- * A vendor-neutral model of a Peppol BIS Billing 3.0 document.
25
+ * Serialize a {@link UblInvoice} into a Peppol BIS Billing 3.0 XML string.
25
26
  *
26
- * This is the intermediate representation the builders in `../` (and, for
27
- * Stripe data, `stripe-ubl`) produce; `./serialize.ts` turns it into UBL XML.
28
- * It is deliberately a thin, construction-oriented mirror of the UBL fields we
29
- * populate — not a full UBL object graph.
30
- */
31
- interface UblAddress {
32
- /** `cbc:StreetName` (BT-35). */
33
- street: string | null;
34
- /** `cbc:AdditionalStreetName` (BT-36). */
35
- additionalStreet: string | null;
36
- /** `cbc:CityName` (BT-37). */
37
- city: string | null;
38
- /** `cbc:PostalZone` (BT-38). */
39
- postalZone: string | null;
40
- /** `cbc:CountrySubentity` (BT-39). */
41
- countrySubentity: string | null;
42
- /** `cac:Country/cbc:IdentificationCode` (BT-40) — ISO 3166-1 alpha-2. */
43
- countryCode: string | null;
44
- }
45
- /** Peppol participant identifier, e.g. scheme `0208`, value `0800279001`. */
46
- interface UblEndpoint {
47
- scheme: string;
48
- value: string;
49
- }
50
- /** Legal registration identifier, e.g. a Belgian enterprise number. */
51
- interface UblCompanyId {
52
- value: string;
53
- /** ICD scheme (e.g. `0208` for the Belgian CBE), when known. */
54
- scheme?: string | null;
55
- }
56
- interface UblParty {
57
- /** `cbc:EndpointID` (BT-49/BT-34) — the Peppol routing identifier. */
58
- endpoint: UblEndpoint | null;
59
- /** `cac:PartyName/cbc:Name` (BT-27/BT-44). */
60
- name: string;
61
- address: UblAddress;
62
- /** `cac:PartyTaxScheme/cbc:CompanyID` with `VAT` scheme (BT-31/BT-48). */
63
- vatNumber: string | null;
64
- /** `cac:PartyLegalEntity/cbc:RegistrationName` (BT-27/BT-44). Defaults to `name`. */
65
- legalName: string | null;
66
- /** `cac:PartyLegalEntity/cbc:CompanyID` (BT-30/BT-47). */
67
- companyId: UblCompanyId | null;
68
- }
69
- /**
70
- * VAT breakdown category. `id` is a UNCL5305 code:
71
- * - `S` Standard rate
72
- * - `Z` Zero-rated goods
73
- * - `E` Exempt from VAT
74
- * - `AE` VAT reverse charge
75
- * - `O` Services outside scope of tax
76
- * - `K` Intra-community supply
77
- * - `G` Export outside the EU
78
- */
79
- interface UblTaxCategory {
80
- id: string;
81
- percent: number;
82
- /** Required by EN 16931 (BR-E-10/BR-AE-10/…) for non-`S`/`Z` categories. */
83
- exemptionReason?: string | null | undefined;
84
- }
85
- interface UblLine {
86
- /** `cbc:ID` (BT-126) — line identifier. */
87
- id: string;
88
- /** `cac:Item/cbc:Name` (BT-153). */
89
- name: string;
90
- /** `cbc:InvoicedQuantity` / `cbc:CreditedQuantity` (BT-129). */
91
- quantity: number;
92
- /** UN/ECE Rec 20 unit code (BT-130). */
93
- unitCode: string;
94
- /** `cbc:LineExtensionAmount` (BT-131) — net of VAT, after line discounts. */
95
- lineExtensionAmount: number;
96
- /** `cac:Price/cbc:PriceAmount` (BT-146) — net unit price. */
97
- priceAmount: number;
98
- /**
99
- * `cac:Price/cbc:BaseQuantity` (BT-149) — the number of units `priceAmount`
100
- * covers. Omitted means 1. Set it when the net doesn't divide evenly into
101
- * cents, so `quantity × (priceAmount ÷ baseQuantity)` reproduces the line
102
- * net exactly (PEPPOL-EN16931-R120); see `deriveUnitPrice`.
103
- */
104
- baseQuantity?: number | undefined;
105
- /** `cac:InvoicePeriod` (BT-134/BT-135) — the line's own service period. */
106
- invoicePeriod?: UblPeriod | null;
107
- taxCategory: UblTaxCategory;
108
- }
109
- interface UblTaxSubtotal {
110
- /** `cbc:TaxableAmount` (BT-116). */
111
- taxableAmount: number;
112
- /** `cbc:TaxAmount` (BT-117). */
113
- taxAmount: number;
114
- category: UblTaxCategory;
115
- }
116
- interface UblTaxTotal {
117
- /** `cbc:TaxAmount` (BT-110) — sum of subtotal tax amounts. */
118
- taxAmount: number;
119
- subtotals: UblTaxSubtotal[];
120
- }
121
- interface UblMonetaryTotal {
122
- /** BT-106 — sum of line net amounts. */
123
- lineExtensionAmount: number;
124
- /** BT-109 — total without VAT. */
125
- taxExclusiveAmount: number;
126
- /** BT-112 — total with VAT. */
127
- taxInclusiveAmount: number;
128
- /**
129
- * BT-113 — sum of amounts paid in advance. **Gross (VAT-inclusive)**, since
130
- * BR-CO-16 subtracts it directly from BT-112. Omitted when absent or zero.
131
- */
132
- prepaidAmount?: number;
133
- /** BT-114 — rounding applied to the payable amount. Omitted when absent or zero. */
134
- payableRoundingAmount?: number;
135
- /**
136
- * BT-115 — amount due for payment, i.e. the *outstanding* amount.
137
- * BR-CO-16: `BT-115 = BT-112 − BT-113 + BT-114`.
138
- */
139
- payableAmount: number;
140
- }
141
- /** An embedded supporting document (BG-24), e.g. the rendered PDF. */
142
- interface UblAttachment {
143
- /** `cac:AdditionalDocumentReference/cbc:ID` (BT-122). */
144
- id: string;
145
- /** `cbc:EmbeddedDocumentBinaryObject/@filename`. */
146
- filename: string;
147
- /** MIME type, e.g. `application/pdf`. */
148
- mimeCode: string;
149
- /** Base64-encoded document bytes. */
150
- base64: string;
151
- }
152
- /**
153
- * A service period: BT-73/BT-74 on the document, BT-134/BT-135 on a line.
154
- * Either bound may stand alone — UBL allows a half-open period — but a period
155
- * with neither is omitted entirely.
27
+ * Emits the subset of the model a Peppol BIS Billing 3.0 document needs:
28
+ * header (`customizationId`, `profileId` and `invoiceTypeCode` default to the
29
+ * BIS values), note, buyer reference, invoice period, billing reference,
30
+ * attachments, parties, payment terms, VAT breakdown, monetary totals and
31
+ * lines with their price and classified VAT category. Payment means,
32
+ * allowances/charges, delivery and the document references are not emitted.
33
+ *
34
+ * @throws {UblBuildError} when a field EN 16931 / Peppol BIS makes mandatory is
35
+ * missing: document id, issue date, currency, seller and buyer name, an
36
+ * endpoint without a scheme, at least one line, per line the quantity, unit
37
+ * code, unit price, net amount and VAT category (id, plus the rate unless the
38
+ * category is `O`), the total VAT amount, the four monetary totals, and for an
39
+ * embedded attachment its filename, MIME code and content.
156
40
  */
157
- interface UblPeriod {
158
- /** `YYYY-MM-DD`. */
159
- startDate: string | null;
160
- /** `YYYY-MM-DD`, inclusive. */
161
- endDate: string | null;
162
- }
163
- interface UblDocument {
164
- documentType: "invoice" | "creditNote";
165
- /** Invoice / credit note number (BT-1). */
166
- id: string;
167
- /** Issue date (BT-2), `YYYY-MM-DD`. */
168
- issueDate: string;
169
- /** Payment due date (BT-9). Invoices only. */
170
- dueDate: string | null;
171
- /** Free-text note (BT-22). */
172
- note: string | null;
173
- /** Payment terms note (BT-20, `cac:PaymentTerms/cbc:Note`). */
174
- paymentTermsNote?: string | null;
175
- /** Document currency (BT-5). */
176
- currency: string;
177
- /** Buyer reference (BT-10). */
178
- buyerReference: string | null;
179
- /** Invoicing period (BT-73/BT-74). */
180
- invoicePeriod?: UblPeriod | null;
181
- /** For credit notes: the referenced original invoice number (BT-25). */
182
- precedingInvoiceId: string | null;
183
- supplier: UblParty;
184
- customer: UblParty;
185
- lines: UblLine[];
186
- taxTotal: UblTaxTotal;
187
- monetaryTotal: UblMonetaryTotal;
188
- attachments: UblAttachment[];
189
- }
190
- //#endregion
191
- //#region src/build/ubl/serialize.d.ts
192
- /** Serialize a {@link UblDocument} into a Peppol BIS Billing 3.0 XML string. */
193
- declare const serializeUblDocument: (doc: UblDocument) => string;
41
+ declare const serializeUblInvoice: (doc: UblInvoice) => string;
42
+ /** Alias of {@link serializeUblInvoice}, kept under the historical name. */
43
+ declare const serializeUblDocument: typeof serializeUblInvoice;
194
44
  //#endregion
195
45
  //#region src/build/address.d.ts
196
46
  /**
@@ -215,7 +65,7 @@ interface AddressInput {
215
65
  }
216
66
  /**
217
67
  * Normalize a free-form address (Stripe shape, custom shape, or an internal
218
- * shape) into a {@link UblAddress}.
68
+ * shape) into a {@link UblAddress}. An absent part is an absent key.
219
69
  *
220
70
  * Accepts both `line1`/`postal_code`/`country` (Stripe) and `street`/`zip_code`
221
71
  * (legacy/internal) keys. Falls back to `fallbackCountryCode` when the address
@@ -265,7 +115,7 @@ interface UblSupplier {
265
115
  /** Peppol participant identifier in `scheme:value` form (e.g. `"0208:0793904121"`). */
266
116
  peppolID?: string | null;
267
117
  }
268
- /** Convert a {@link UblSupplier} into the supplier (seller) party. */
118
+ /** Convert a {@link UblSupplier} into the seller party (`cac:AccountingSupplierParty`). */
269
119
  declare const buildSupplierParty: (supplier: UblSupplier) => UblParty;
270
120
  /**
271
121
  * Caller-provided customer (buyer) data, normalized into a stable shape.
@@ -296,7 +146,7 @@ interface UblCustomer {
296
146
  vatNumber?: string | null;
297
147
  }
298
148
  /**
299
- * Convert a {@link UblCustomer} into the customer (buyer) party.
149
+ * Convert a {@link UblCustomer} into the buyer party (`cac:AccountingCustomerParty`).
300
150
  *
301
151
  * The Peppol `EndpointID` (BT-49) — which routes the document — is resolved in
302
152
  * priority order: an explicit `endpointOverride` (e.g. a confirmed-registered
@@ -322,9 +172,9 @@ declare const buildPdfAttachment: (params: {
322
172
  }) => UblAttachment;
323
173
  /**
324
174
  * Replace each attachment's base64 payload with `[omitted]` plus a length, so a
325
- * {@link UblDocument} is safe to log or persist for audit.
175
+ * {@link UblInvoice} is safe to log or persist for audit.
326
176
  */
327
- declare const sanitizeUblDocumentForAudit: (doc: UblDocument) => UblDocument;
177
+ declare const sanitizeUblDocumentForAudit: (doc: UblInvoice) => UblInvoice;
328
178
  //#endregion
329
179
  //#region src/build/identifiers.d.ts
330
180
  /**
@@ -339,22 +189,22 @@ declare const normalizeCompanyNumberForCountry: (countryCode: string | null | un
339
189
  * `@financica/peppol`'s country profiles.
340
190
  *
341
191
  * Falls back to inspecting the number's country prefix (e.g. `BE0793904121`).
342
- * Returns `null` when the scheme can't be determined, in which case the
192
+ * Returns `undefined` when the scheme can't be determined, in which case the
343
193
  * CompanyID is emitted without a `schemeID` attribute.
344
194
  */
345
195
  declare const resolveCompanyIdScheme: (params: {
346
196
  countryCode: string | null;
347
197
  companyNumber: string | null;
348
- }) => string | null;
198
+ }) => string | undefined;
349
199
  /**
350
200
  * Build the `cac:PartyLegalEntity/cbc:CompanyID` value for a party, with the
351
- * country-appropriate ICD scheme when known. Returns `null` when there is no
201
+ * country-appropriate ICD scheme when known. Returns `undefined` when there is no
352
202
  * company number.
353
203
  */
354
204
  declare const buildCompanyId: (params: {
355
205
  countryCode: string | null;
356
206
  companyNumber: string | null;
357
- }) => UblCompanyId | null;
207
+ }) => UblCompanyId | undefined;
358
208
  /**
359
209
  * Resolve the Peppol participant identifier for a VAT number, deriving the EAS
360
210
  * scheme from the number's own country prefix (falling back to `countryCode`).
@@ -362,25 +212,25 @@ declare const buildCompanyId: (params: {
362
212
  * `BE0206582284` → `{ scheme: "9925", value: "BE0206582284" }`
363
213
  *
364
214
  * The scheme comes from `@financica/peppol`'s country resolution, so countries
365
- * that route on their registry number alone (Norway, Denmark) yield `null`
215
+ * that route on their registry number alone (Norway, Denmark) yield `undefined`
366
216
  * here — their VAT number is not a Peppol participant identifier.
367
217
  *
368
218
  * The value keeps its country prefix, matching how participants register (the
369
- * Peppol directory lists this party as `9925:be0206582284`). Returns `null`
219
+ * Peppol directory lists this party as `9925:be0206582284`). Returns `undefined`
370
220
  * when the country has no VAT EAS scheme or the input is empty.
371
221
  */
372
222
  declare const resolveVatEndpoint: (params: {
373
223
  vatNumber: string | null | undefined;
374
224
  countryCode?: string | null | undefined;
375
- }) => UblEndpoint | null;
225
+ }) => UblEndpoint | undefined;
376
226
  /**
377
227
  * Parse a Peppol participant identifier into a {@link UblEndpoint}.
378
228
  *
379
229
  * Accepts the canonical `scheme:value` form (e.g. `0208:0800279001`). Returns
380
- * `null` for values without an explicit scheme, since `cbc:EndpointID` requires
230
+ * `undefined` for values without an explicit scheme, since `cbc:EndpointID` requires
381
231
  * a `schemeID` and guessing one would mis-route the document.
382
232
  */
383
- declare const parsePeppolEndpoint: (peppolId: string | null | undefined) => UblEndpoint | null;
233
+ declare const parsePeppolEndpoint: (peppolId: string | null | undefined) => UblEndpoint | undefined;
384
234
  interface CustomerTaxIdentifiers {
385
235
  peppolID: string | null;
386
236
  glnNumber: string | null;
@@ -430,28 +280,34 @@ declare const listPeppolReceiverIdentifierCandidates: (customer: Partial<Custome
430
280
  declare const roundCurrency: (value: number) => number;
431
281
  /** Convert an integer cent amount into a 2-decimal currency value. */
432
282
  declare const centsToDecimal: (cents: number) => number;
433
- /** The `cac:Price` pair for a line: BT-146 and the optional BT-149. */
283
+ /** The `cac:Price` pair for a line: the per-unit price and the optional BT-149. */
434
284
  interface UnitPrice {
435
- /** `cbc:PriceAmount` (BT-146). */
436
- priceAmount: number;
437
- /** `cbc:BaseQuantity` (BT-149) — the units `priceAmount` covers. Omitted = 1. */
285
+ /** Net price of one unit (`UblLine.unitPrice`). */
286
+ unitPrice: number;
287
+ /**
288
+ * `cbc:BaseQuantity` (BT-149) — set when the per-unit price is not exact in
289
+ * cents; the serializer then emits `PriceAmount = unitPrice × baseQuantity`
290
+ * (the line net). Omitted = 1.
291
+ */
438
292
  baseQuantity?: number | undefined;
439
293
  }
440
294
  /**
441
295
  * Derive the `cac:Price` for a line whose net total is authoritative.
442
296
  *
443
297
  * Peppol rule PEPPOL-EN16931-R120 checks
444
- * `quantity × (priceAmount ÷ baseQuantity)` against the line net amount within
298
+ * `quantity × (PriceAmount ÷ BaseQuantity)` against the line net amount within
445
299
  * a 0.02 tolerance. Naively rounding `net ÷ quantity` to cents breaks that
446
300
  * whenever the division doesn't land on a cent: 940.00 over 14 units gives
447
301
  * 67.142857…, which rounds to 67.14, and 14 × 67.14 = 939.96 — off by 0.04 and
448
302
  * rejected as a fatal validation error.
449
303
  *
450
304
  * So the cent-rounded unit price is only used when it reproduces the net
451
- * exactly. Otherwise the line is priced as a whole via BT-149 (`priceAmount` =
452
- * the net, `baseQuantity` = the quantity), which is exact at any magnitude
453
- * instead of merely within tolerance — the residual of a rounded unit price
454
- * grows with quantity and would eventually breach 0.02 at any fixed precision.
305
+ * exactly. Otherwise the line is priced as a whole via BT-149: `unitPrice` is
306
+ * the exact (unrounded) `net ÷ quantity` and `baseQuantity` = the quantity, so
307
+ * the serializer writes `PriceAmount` = the net and `BaseQuantity` = the
308
+ * quantity, which is exact at any magnitude instead of merely within tolerance
309
+ * — the residual of a rounded unit price grows with quantity and would
310
+ * eventually breach 0.02 at any fixed precision.
455
311
  */
456
312
  declare const deriveUnitPrice: (netTotal: number, quantity: number) => UnitPrice;
457
313
  //#endregion
@@ -538,6 +394,9 @@ interface BuildTaxTotalsOptions {
538
394
  * invariant holds by construction. The result is *not* clamped: a prepayment
539
395
  * exceeding the total yields a negative payable amount, surfacing the upstream
540
396
  * overpayment rather than hiding it.
397
+ *
398
+ * @throws {UblBuildError} for a line without a `taxCategory` — there is no
399
+ * VAT breakdown to put it in.
541
400
  */
542
401
  declare const buildTaxTotals: (lines: UblLine[], options?: BuildTaxTotalsOptions) => BuildTaxTotalsResult;
543
402
  //#endregion
@@ -572,5 +431,11 @@ declare const el: (name: string, attrs?: XmlAttrs | null, content?: string | num
572
431
  /** Serialize a root element into a UTF-8 XML document string. */
573
432
  declare const serializeDocument: (root: XmlElement) => string;
574
433
  //#endregion
575
- export { type AddressInput, type BuildTaxTotalsOptions, type BuildTaxTotalsResult, COUNTRY_CODE_LIST_ID, CREDIT_NOTE_TYPE_CODE, type CustomerTaxIdInput, type CustomerTaxIdentifiers, DEFAULT_UNIT_CODE, EXEMPT_TAXABILITY_REASONS, INVOICE_TYPE_CODE, NS_CAC, NS_CBC, NS_CREDIT_NOTE, NS_INVOICE, type SupplierVatStatus, type TaxAmountInfo, UBL_CUSTOMIZATION_ID, UBL_PROFILE_ID, type UblAddress, type UblAttachment, type UblCompanyId, type UblCustomer, type UblDocument, type UblEndpoint, type UblLine, type UblMonetaryTotal, type UblParty, type UblPeriod, type UblSupplier, type UblTaxCategory, type UblTaxSubtotal, type UblTaxTotal, type UnitPrice, VAT_TAX_SCHEME_ID, type XmlAttrs, type XmlElement, buildCompanyId, buildCustomerParty, buildPdfAttachment, buildSupplierParty, buildTaxTotals, centsToDecimal, coerceLinesForSupplierVatStatus, deriveUnitPrice, el, extractCustomerTaxIdentifiers, listPeppolReceiverIdentifierCandidates, normalizeAddress, normalizeCompanyNumberForCountry, parsePeppolEndpoint, reconcileLinesToExclTotal, resolveCompanyIdScheme, resolveTaxCategoryFromTaxAmounts, resolveVatEndpoint, roundCurrency, sanitizeUblDocumentForAudit, serializeDocument, serializeUblDocument, taxCategoryFromReasonOrRate };
434
+ //#region src/build/index.d.ts
435
+ /** @deprecated The build and parse models are one; use {@link UblInvoice}. */
436
+ type UblDocument = UblInvoice;
437
+ /** @deprecated Use {@link UblInvoicePeriod}. */
438
+ type UblPeriod = UblInvoicePeriod;
439
+ //#endregion
440
+ export { type AddressInput, type BuildTaxTotalsOptions, type BuildTaxTotalsResult, COUNTRY_CODE_LIST_ID, CREDIT_NOTE_TYPE_CODE, type CustomerTaxIdInput, type CustomerTaxIdentifiers, DEFAULT_UNIT_CODE, EXEMPT_TAXABILITY_REASONS, INVOICE_TYPE_CODE, NS_CAC, NS_CBC, NS_CREDIT_NOTE, NS_INVOICE, type SupplierVatStatus, type TaxAmountInfo, UBL_CUSTOMIZATION_ID, UBL_PROFILE_ID, type UblAddress, type UblAttachment, type UblBillingReference, UblBuildError, type UblCompanyId, type UblCustomer, UblDocument, type UblEndpoint, type UblInvoice, type UblInvoicePeriod, type UblLine, type UblMonetaryTotal, type UblParty, UblPeriod, type UblSupplier, type UblTaxCategory, type UblTaxSubtotal, type UblTaxTotal, type UnitPrice, VAT_TAX_SCHEME_ID, type XmlAttrs, type XmlElement, buildCompanyId, buildCustomerParty, buildPdfAttachment, buildSupplierParty, buildTaxTotals, centsToDecimal, coerceLinesForSupplierVatStatus, deriveUnitPrice, el, extractCustomerTaxIdentifiers, listPeppolReceiverIdentifierCandidates, normalizeAddress, normalizeCompanyNumberForCountry, parsePeppolEndpoint, reconcileLinesToExclTotal, resolveCompanyIdScheme, resolveTaxCategoryFromTaxAmounts, resolveVatEndpoint, roundCurrency, sanitizeUblDocumentForAudit, serializeDocument, serializeUblDocument, serializeUblInvoice, taxCategoryFromReasonOrRate };
576
441
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../../src/build/ubl/constants.ts","../../src/build/ubl/types.ts","../../src/build/ubl/serialize.ts","../../src/build/address.ts","../../src/build/party.ts","../../src/build/attachment.ts","../../src/build/identifiers.ts","../../src/build/numeric.ts","../../src/build/tax-category.ts","../../src/build/tax-totals.ts","../../src/build/xml.ts"],"mappings":";;;cAGa;;cAIA;;cAGA;;cAEA;;cAGA;;cAGA;;cAGA;cAEA;cACA;cAEA;cAEA;;;;;;;;;;;UCnBI;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;UAIgB;EAChB;EACA;;;UAIgB;EAChB;;EAEA;;UAGgB;;EAEhB,UAAU;;EAEV;EACA,SAAS;;EAET;;EAEA;;EAEA,WAAW;;;;;;;;;;;;UAaK;EAChB;EACA;;EAEA;;UAGgB;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;EAOA;;EAEA,gBAAgB;EAChB,aAAa;;UAGG;;EAEhB;;EAEA;EACA,UAAU;;UAGM;;EAEhB;EACA,WAAW;;UAGK;;EAEhB;;EAEA;;EAEA;;;;;EAKA;;EAEA;;;;;EAKA;;;UAIgB;;EAEhB;;EAEA;;EAEA;;EAEA;;;;;;;UAQgB;;EAEhB;;EAEA;;UAGgB;EAChB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA,gBAAgB;;EAEhB;EACA,UAAU;EACV,UAAU;EACV,OAAO;EACP,UAAU;EACV,eAAe;EACf,aAAa;;;;;cC6BD,uBAAoB,KAAS;;;;;;;;;;;UC7LzB;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;cAYY,mBAAgB,SACnB,iCAA+B,oCACN,iCAEhC;;;;;;;;;;;;;;;;;KCxBS;;;;;;;UAQK;;EAEhB;;EAEA;;;;;EAKA,SAAS;;EAET;;EAEA;;EAEA,WAAW;;EAEX;;;cAIY,qBAAkB,UAAc,gBAAc;;;;;;;;UAsB1C;;EAEhB;;EAEA,SAAS;;;;;;;EAOT;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;cAcY,qBAAkB,UACpB,aAAW,mBACF,uBACjB;;;;;;;;cCnGU,qBAAkB;EAC9B;EACA,OAAO;;EAEP;MACG;;;;;cAWS,8BAA2B,KAAS,gBAAc;;;;;;;cCLlD,mCAAgC,wCACN;;;;;;;;;;;cAmB1B,yBAAsB;EAClC;EACA;;;;;;;cAuBY,iBAAc;EAC1B;EACA;MACG;;;;;;;;;;;;;;;cA4BS,qBAAkB;EAC9B;EACA;MACG;;;;;;;;cAyBS,sBAAmB,wCAE7B;UAWc;EAChB;EACA;EACA;EACA;;;;;;;UAQgB;EAChB;EACA;;;;;;;;;cAaY,gCAA6B,iBACxB,4CACf;;;;;;;;;;;;;;;;;;;;cAkDU,yCAAsC,UACxC,QAAQ,yBAAuB;;;;cCtN7B,gBAAa;;cAIb,iBAAc;;UAGV;;EAEhB;;EAEA;;;;;;;;;;;;;;;;;;cAmBY,kBAAe,kBAAoB,qBAAqB;;;;;;;cCvBxD,2BAAyB;UAsBrB;EAChB;EACA;EACA;;;;;;;;;;;;;cAiBY,8BAA2B;EACvC;EACA;EACA;MACG;;;;;;;cA6CS,mCAAgC,YAChC,iBAAe,iBAEzB;;;;;;;cAiCU,kCAA+B,OACpC,WAAS,WACL,mBAAiB,wCAE1B;;;;;;;;;;;;;cCxHU,4BAAyB,OAC9B,WAAS,sCAEd;UAoCc;EAChB,UAAU;EACV,eAAe;;UAGC;;;;;;EAMhB;;EAEA;;;;;;;;;;;;;;;;;;cAmBY,iBAAc,OACnB,WAAS,UACN,0BACR;;;;;;;;;;;KCpFS,WAAW;UAEN;EAChB;EACA,QAAQ;;EAER;;EAEA,WAAW;;;KAIP,YAAY;;;;;;;;cASJ,KAAE,cACF,QACJ,iBAAe,mCACY,gBACjC;;cAgDU,oBAAiB,MAAU"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../../src/build/ubl/constants.ts","../../src/build/ubl/serialize.ts","../../src/build/address.ts","../../src/build/party.ts","../../src/build/attachment.ts","../../src/build/identifiers.ts","../../src/build/numeric.ts","../../src/build/tax-category.ts","../../src/build/tax-totals.ts","../../src/build/xml.ts","../../src/build/index.ts"],"mappings":";;;;cAGa;;cAIA;;cAGA;;cAEA;;cAGA;;cAGA;;cAGA;cAEA;cACA;cAEA;cAEA;;;;;;;;;;;;;;;;;;;;cCwVA,sBAAmB,KAAS;;cAgE5B,6BAAoB;;;;;;;;;;;UCnahB;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;cAYY,mBAAgB,SACnB,iCAA+B,oCACN,iCAEhC;;;;;;;;;;;;;;;;;KCxBS;;;;;;;UAQK;;EAEhB;;EAEA;;;;;EAKA,SAAS;;EAET;;EAEA;;EAEA,WAAW;;EAEX;;;cAIY,qBAAkB,UAAc,gBAAc;;;;;;;;UAsB1C;;EAEhB;;EAEA,SAAS;;;;;;;EAOT;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;cAcY,qBAAkB,UACpB,aAAW,mBACF,uBACjB;;;;;;;;cCnGU,qBAAkB;EAC9B;EACA,OAAO;;EAEP;MACG;;;;;cAWS,8BAA2B,KAAS,eAAa;;;;;;;cCLjD,mCAAgC,wCACN;;;;;;;;;;;cAmB1B,yBAAsB;EAClC;EACA;;;;;;;cAuBY,iBAAc;EAC1B;EACA;MACG;;;;;;;;;;;;;;;cA4BS,qBAAkB;EAC9B;EACA;MACG;;;;;;;;cAyBS,sBAAmB,wCAE7B;UAWc;EAChB;EACA;EACA;EACA;;;;;;;UAQgB;EAChB;EACA;;;;;;;;;cAaY,gCAA6B,iBACxB,4CACf;;;;;;;;;;;;;;;;;;;;cAkDU,yCAAsC,UACxC,QAAQ,yBAAuB;;;;cCtN7B,gBAAa;;cAIb,iBAAc;;UAGV;;EAEhB;;;;;;EAMA;;;;;;;;;;;;;;;;;;;;cAqBY,kBAAe,kBAAoB,qBAAqB;;;;;;;cC7BxD,2BAAyB;UAsBrB;EAChB;EACA;EACA;;;;;;;;;;;;;cAiBY,8BAA2B;EACvC;EACA;EACA;MACG;;;;;;;cA8CS,mCAAgC,YAChC,iBAAe,iBAEzB;;;;;;;cAiCU,kCAA+B,OACpC,WAAS,WACL,mBAAiB,wCAE1B;;;;;;;;;;;;;cCrHU,4BAAyB,OAC9B,WAAS,sCAEd;UAmCc;EAChB,UAAU;EACV,eAAe;;UAGC;;;;;;EAMhB;;EAEA;;;;;;;;;;;;;;;;;;;;;cAsBY,iBAAc,OACnB,WAAS,UACN,0BACR;;;;;;;;;;;KC1FS,WAAW;UAEN;EAChB;EACA,QAAQ;;EAER;;EAEA,WAAW;;;KAIP,YAAY;;;;;;;;cASJ,KAAE,cACF,QACJ,iBAAe,mCACY,gBACjC;;cAgDU,oBAAiB,MAAU;;;;KCpD5B,cAAc;;KAEd,YAAY"}