@financica/ubl 0.15.1 → 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.
@@ -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,192 +20,76 @@ 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.
26
+ *
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.
25
33
  *
26
- * This is the intermediate representation `stripe-ubl` produces from a Stripe
27
- * invoice or credit note; {@link ../ubl/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.
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.
30
40
  */
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
- }
41
+ declare const serializeUblInvoice: (doc: UblInvoice) => string;
42
+ /** Alias of {@link serializeUblInvoice}, kept under the historical name. */
43
+ declare const serializeUblDocument: typeof serializeUblInvoice;
44
+ //#endregion
45
+ //#region src/build/address.d.ts
69
46
  /**
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
47
+ * A free-form postal address as accepted by {@link normalizeAddress}.
48
+ *
49
+ * Both the Stripe shape (`line1`, `postal_code`, `country`, `state`) and the
50
+ * legacy/internal shape (`street`, `zip_code`, `country_code`,
51
+ * `country_subentity`) are accepted; when both keys are present the Stripe
52
+ * one wins.
78
53
  */
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;
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;
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;
54
+ interface AddressInput {
55
+ line1?: string | null;
56
+ line2?: string | null;
57
+ street?: string | null;
58
+ city?: string | null;
59
+ postal_code?: string | null;
60
+ zip_code?: string | null;
61
+ state?: string | null;
62
+ country_subentity?: string | null;
63
+ country?: string | null;
64
+ country_code?: string | null;
151
65
  }
152
66
  /**
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.
67
+ * Normalize a free-form address (Stripe shape, custom shape, or an internal
68
+ * shape) into a {@link UblAddress}. An absent part is an absent key.
69
+ *
70
+ * Accepts both `line1`/`postal_code`/`country` (Stripe) and `street`/`zip_code`
71
+ * (legacy/internal) keys. Falls back to `fallbackCountryCode` when the address
72
+ * has no country, but never silently substitutes a caller's country — pass
73
+ * `null` when "no country" is the right answer.
156
74
  */
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;
75
+ declare const normalizeAddress: (address: AddressInput | null | undefined, fallbackCountryCode: string | null, fallbackLine?: string | null) => UblAddress;
194
76
  //#endregion
195
77
  //#region src/build/party.d.ts
196
78
  /**
197
79
  * Supplier (seller) VAT status. Drives how zero-VAT lines are reported when the
198
80
  * seller does not charge VAT:
199
81
  *
200
- * 1 — Subject to VAT (the normal case): line categories come from the data.
201
- * 2 — Not subject to VAT.
202
- * 3 — Small business / franchise exemption (e.g. Belgian Article 56bis).
82
+ * - `subject` — subject to VAT (the normal case): line categories come from
83
+ * the data.
84
+ * - `not_subject` — not subject to VAT.
85
+ * - `small_business` — small business / franchise exemption (e.g. Belgian
86
+ * Article 56bis).
203
87
  *
204
- * For statuses 2 and 3, {@link ../build.ts} coerces all line categories to a
205
- * non-charging exempt category so no VAT is reported.
88
+ * For the last two, `coerceLinesForSupplierVatStatus` (tax-category.ts) turns
89
+ * every line into a non-charging exempt category so no VAT is reported.
90
+ * Providers that encode this numerically (Scrada: 1/2/3) map at their boundary.
206
91
  */
207
- type SupplierVatStatus = 1 | 2 | 3;
92
+ type SupplierVatStatus = "subject" | "not_subject" | "small_business";
208
93
  /**
209
94
  * Caller-provided supplier data, normalized into a stable shape.
210
95
  *
@@ -220,7 +105,7 @@ interface UblSupplier {
220
105
  * Free-form address. Stripe-style fields (`line1`, `postal_code`, `country`)
221
106
  * and legacy/internal fields (`street`, `zip_code`) are both accepted.
222
107
  */
223
- address: unknown;
108
+ address: AddressInput | null;
224
109
  /** Country-specific company/registration number (e.g. BE enterprise number). */
225
110
  companyNumber?: string | null;
226
111
  /** VAT number with country prefix (e.g. `"BE0793904121"`). */
@@ -230,7 +115,7 @@ interface UblSupplier {
230
115
  /** Peppol participant identifier in `scheme:value` form (e.g. `"0208:0793904121"`). */
231
116
  peppolID?: string | null;
232
117
  }
233
- /** Convert a {@link UblSupplier} into the supplier (seller) party. */
118
+ /** Convert a {@link UblSupplier} into the seller party (`cac:AccountingSupplierParty`). */
234
119
  declare const buildSupplierParty: (supplier: UblSupplier) => UblParty;
235
120
  /**
236
121
  * Caller-provided customer (buyer) data, normalized into a stable shape.
@@ -261,7 +146,7 @@ interface UblCustomer {
261
146
  vatNumber?: string | null;
262
147
  }
263
148
  /**
264
- * Convert a {@link UblCustomer} into the customer (buyer) party.
149
+ * Convert a {@link UblCustomer} into the buyer party (`cac:AccountingCustomerParty`).
265
150
  *
266
151
  * The Peppol `EndpointID` (BT-49) — which routes the document — is resolved in
267
152
  * priority order: an explicit `endpointOverride` (e.g. a confirmed-registered
@@ -273,18 +158,6 @@ interface UblCustomer {
273
158
  */
274
159
  declare const buildCustomerParty: (customer: UblCustomer, endpointOverride?: UblEndpoint | null) => UblParty;
275
160
  //#endregion
276
- //#region src/build/address.d.ts
277
- /**
278
- * Normalize a free-form address (Stripe shape, custom shape, or an internal
279
- * shape) into a {@link UblAddress}.
280
- *
281
- * Accepts both `line1`/`postal_code`/`country` (Stripe) and `street`/`zip_code`
282
- * (legacy/internal) keys. Falls back to `fallbackCountryCode` when the address
283
- * has no country, but never silently substitutes a caller's country — pass
284
- * `null` when "no country" is the right answer.
285
- */
286
- declare const normalizeAddress: (address: unknown, fallbackCountryCode: string | null, fallbackLine?: string | null) => UblAddress;
287
- //#endregion
288
161
  //#region src/build/attachment.d.ts
289
162
  /**
290
163
  * Build a UBL embedded-document attachment (BG-24) from raw bytes — e.g. the
@@ -299,69 +172,80 @@ declare const buildPdfAttachment: (params: {
299
172
  }) => UblAttachment;
300
173
  /**
301
174
  * Replace each attachment's base64 payload with `[omitted]` plus a length, so a
302
- * {@link UblDocument} is safe to log or persist for audit.
175
+ * {@link UblInvoice} is safe to log or persist for audit.
303
176
  */
304
- declare const sanitizeUblDocumentForAudit: (doc: UblDocument) => UblDocument;
177
+ declare const sanitizeUblDocumentForAudit: (doc: UblInvoice) => UblInvoice;
305
178
  //#endregion
306
179
  //#region src/build/identifiers.d.ts
307
180
  /**
308
181
  * Strip whitespace/punctuation from a country-specific company number.
309
182
  * For Belgium, also strips an optional `BE` prefix.
310
183
  */
311
- declare const normalizeCompanyNumberForCountry: (countryCode: string | null | undefined, companyNumber: string | null | undefined) => string;
184
+ declare const normalizeCompanyNumberForCountry: (countryCode: string | null | undefined, companyNumber: string | null | undefined) => any;
312
185
  /**
313
- * Country code → Peppol/ISO 6523 ICD scheme for a legal registration number
314
- * (`cac:PartyLegalEntity/cbc:CompanyID/@schemeID`).
315
- *
316
- * BE → 0208 (Belgian enterprise number, CBE/KBO/BCE)
317
- * NL → 0106 (Netherlands KvK)
318
- * FR → 0002 (France SIRENE)
186
+ * Peppol/ISO 6523 ICD scheme for a legal registration number
187
+ * (`cac:PartyLegalEntity/cbc:CompanyID/@schemeID`), e.g. BE → `0208`
188
+ * (enterprise number), NL → `0106` (KvK), FR → `0002` (SIRENE). The table is
189
+ * `@financica/peppol`'s country profiles.
319
190
  *
320
191
  * Falls back to inspecting the number's country prefix (e.g. `BE0793904121`).
321
- * 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
322
193
  * CompanyID is emitted without a `schemeID` attribute.
323
194
  */
324
195
  declare const resolveCompanyIdScheme: (params: {
325
196
  countryCode: string | null;
326
197
  companyNumber: string | null;
327
- }) => string | null;
198
+ }) => string | undefined;
328
199
  /**
329
200
  * Build the `cac:PartyLegalEntity/cbc:CompanyID` value for a party, with the
330
- * 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
331
202
  * company number.
332
203
  */
333
204
  declare const buildCompanyId: (params: {
334
205
  countryCode: string | null;
335
206
  companyNumber: string | null;
336
- }) => UblCompanyId | null;
207
+ }) => UblCompanyId | undefined;
337
208
  /**
338
209
  * Resolve the Peppol participant identifier for a VAT number, deriving the EAS
339
210
  * scheme from the number's own country prefix (falling back to `countryCode`).
340
211
  *
341
212
  * `BE0206582284` → `{ scheme: "9925", value: "BE0206582284" }`
342
213
  *
214
+ * The scheme comes from `@financica/peppol`'s country resolution, so countries
215
+ * that route on their registry number alone (Norway, Denmark) yield `undefined`
216
+ * here — their VAT number is not a Peppol participant identifier.
217
+ *
343
218
  * The value keeps its country prefix, matching how participants register (the
344
- * Peppol directory lists this party as `9925:be0206582284`). Returns `null`
219
+ * Peppol directory lists this party as `9925:be0206582284`). Returns `undefined`
345
220
  * when the country has no VAT EAS scheme or the input is empty.
346
221
  */
347
222
  declare const resolveVatEndpoint: (params: {
348
223
  vatNumber: string | null | undefined;
349
- countryCode?: string | null;
350
- }) => UblEndpoint | null;
224
+ countryCode?: string | null | undefined;
225
+ }) => UblEndpoint | undefined;
351
226
  /**
352
227
  * Parse a Peppol participant identifier into a {@link UblEndpoint}.
353
228
  *
354
229
  * Accepts the canonical `scheme:value` form (e.g. `0208:0800279001`). Returns
355
- * `null` for values without an explicit scheme, since `cbc:EndpointID` requires
230
+ * `undefined` for values without an explicit scheme, since `cbc:EndpointID` requires
356
231
  * a `schemeID` and guessing one would mis-route the document.
357
232
  */
358
- declare const parsePeppolEndpoint: (peppolId: string | null | undefined) => UblEndpoint | null;
233
+ declare const parsePeppolEndpoint: (peppolId: string | null | undefined) => UblEndpoint | undefined;
359
234
  interface CustomerTaxIdentifiers {
360
235
  peppolID: string | null;
361
236
  glnNumber: string | null;
362
237
  taxNumber: string | null;
363
238
  vatNumber: string | null;
364
239
  }
240
+ /**
241
+ * One customer tax identifier as stored by Stripe (`customer_tax_ids[]`) or an
242
+ * equivalent `{type, value}` pair. `type` is a Stripe tax-ID type such as
243
+ * `eu_vat`, or a custom type such as `peppol_id`; blank entries are skipped.
244
+ */
245
+ interface CustomerTaxIdInput {
246
+ type: string | null | undefined;
247
+ value: string | null | undefined;
248
+ }
365
249
  /**
366
250
  * Pick the first usable Peppol identifier, GLN, VAT number, and tax number
367
251
  * from a Stripe-style `customer_tax_ids` array (`[{type, value}, …]`).
@@ -369,7 +253,7 @@ interface CustomerTaxIdentifiers {
369
253
  * Stripe stores VAT numbers under types like `eu_vat`, `gb_vat`, etc.
370
254
  * Peppol IDs are typically stored as a custom `peppol_id` type.
371
255
  */
372
- declare const extractCustomerTaxIdentifiers: (taxIds: unknown) => CustomerTaxIdentifiers;
256
+ declare const extractCustomerTaxIdentifiers: (taxIds: readonly CustomerTaxIdInput[] | null | undefined) => CustomerTaxIdentifiers;
373
257
  /**
374
258
  * Build the fully-qualified Peppol participant identifiers (`scheme:value`) a
375
259
  * receiver lookup will accept, in priority order, de-duplicated.
@@ -389,40 +273,41 @@ declare const extractCustomerTaxIdentifiers: (taxIds: unknown) => CustomerTaxIde
389
273
  * `countryCode` (the customer's country, when known) disambiguates schemes for
390
274
  * identifiers that don't carry a country prefix (GLN, plain tax numbers).
391
275
  */
392
- declare const listPeppolReceiverIdentifierCandidates: (customer: {
393
- peppolID?: string | null;
394
- glnNumber?: string | null;
395
- taxNumber?: string | null;
396
- vatNumber?: string | null;
397
- }, countryCode?: string | null) => string[];
276
+ declare const listPeppolReceiverIdentifierCandidates: (customer: Partial<CustomerTaxIdentifiers>, countryCode?: string | null) => string[];
398
277
  //#endregion
399
278
  //#region src/build/numeric.d.ts
400
279
  /** Round a number to 2 decimal places (cents). */
401
280
  declare const roundCurrency: (value: number) => number;
402
281
  /** Convert an integer cent amount into a 2-decimal currency value. */
403
282
  declare const centsToDecimal: (cents: number) => number;
404
- /** 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. */
405
284
  interface UnitPrice {
406
- /** `cbc:PriceAmount` (BT-146). */
407
- priceAmount: number;
408
- /** `cbc:BaseQuantity` (BT-149) — the units `priceAmount` covers. Omitted = 1. */
409
- baseQuantity?: number;
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
+ */
292
+ baseQuantity?: number | undefined;
410
293
  }
411
294
  /**
412
295
  * Derive the `cac:Price` for a line whose net total is authoritative.
413
296
  *
414
297
  * Peppol rule PEPPOL-EN16931-R120 checks
415
- * `quantity × (priceAmount ÷ baseQuantity)` against the line net amount within
298
+ * `quantity × (PriceAmount ÷ BaseQuantity)` against the line net amount within
416
299
  * a 0.02 tolerance. Naively rounding `net ÷ quantity` to cents breaks that
417
300
  * whenever the division doesn't land on a cent: 940.00 over 14 units gives
418
301
  * 67.142857…, which rounds to 67.14, and 14 × 67.14 = 939.96 — off by 0.04 and
419
302
  * rejected as a fatal validation error.
420
303
  *
421
304
  * So the cent-rounded unit price is only used when it reproduces the net
422
- * exactly. Otherwise the line is priced as a whole via BT-149 (`priceAmount` =
423
- * the net, `baseQuantity` = the quantity), which is exact at any magnitude
424
- * instead of merely within tolerance — the residual of a rounded unit price
425
- * 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.
426
311
  */
427
312
  declare const deriveUnitPrice: (netTotal: number, quantity: number) => UnitPrice;
428
313
  //#endregion
@@ -460,6 +345,13 @@ declare const taxCategoryFromReasonOrRate: (params: {
460
345
  * otherwise the rate decides standard (`S`) vs zero-rated (`Z`).
461
346
  */
462
347
  declare const resolveTaxCategoryFromTaxAmounts: (taxAmounts: TaxAmountInfo[], rate: number) => UblTaxCategory;
348
+ /**
349
+ * When the supplier does not charge VAT, coerce every line to a non-charging
350
+ * exempt category (`E`, 0%) with the appropriate BT-120 reason, so the document
351
+ * reports no VAT regardless of what the upstream line tax data implied. Lines
352
+ * are returned untouched for a `subject` supplier.
353
+ */
354
+ declare const coerceLinesForSupplierVatStatus: (lines: UblLine[], vatStatus: SupplierVatStatus, supplierCountryCode?: string | null) => UblLine[];
463
355
  //#endregion
464
356
  //#region src/build/tax-totals.d.ts
465
357
  /**
@@ -502,6 +394,9 @@ interface BuildTaxTotalsOptions {
502
394
  * invariant holds by construction. The result is *not* clamped: a prepayment
503
395
  * exceeding the total yields a negative payable amount, surfacing the upstream
504
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.
505
400
  */
506
401
  declare const buildTaxTotals: (lines: UblLine[], options?: BuildTaxTotalsOptions) => BuildTaxTotalsResult;
507
402
  //#endregion
@@ -536,5 +431,11 @@ declare const el: (name: string, attrs?: XmlAttrs | null, content?: string | num
536
431
  /** Serialize a root element into a UTF-8 XML document string. */
537
432
  declare const serializeDocument: (root: XmlElement) => string;
538
433
  //#endregion
539
- export { type BuildTaxTotalsOptions, type BuildTaxTotalsResult, COUNTRY_CODE_LIST_ID, CREDIT_NOTE_TYPE_CODE, 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, 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 };
540
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/party.ts","../../src/build/address.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;;;;;;;;;;;;;;KC9L9B;;;;;;;UAQK;;EAEhB;;EAEA;;;;;EAKA;;EAEA;;EAEA;;EAEA,WAAW;;EAEX;;;cAIY,qBAAkB,UAAc,gBAAc;;;;;;;;UAsB1C;;EAEhB;;EAEA,SAAS;;;;;;;EAOT;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;cAcY,qBAAkB,UACpB,aAAW,mBACF,uBACjB;;;;;;;;;;;;cCrFU,mBAAgB,kBACZ,oCACkB,iCAEhC;;;;;;;;cCfU,qBAAkB;EAC9B;EACA,OAAO;;EAEP;MACG;;;;;cAWS,8BAA2B,KAAS,gBAAc;;;;;;;cCTlD,mCAAgC,wCACN;;;;;;;;;;;;;cAqB1B,yBAAsB;EAClC;EACA;;;;;;;cA8BY,iBAAc;EAC1B;EACA;MACG;;;;;;;;;;;cAkFS,qBAAkB;EAC9B;EACA;MACG;;;;;;;;cAiCS,sBAAmB,wCAE7B;UAWc;EAChB;EACA;EACA;EACA;;;;;;;;;cAaY,gCAA6B,oBAEvC;;;;;;;;;;;;;;;;;;;;cAwDU,yCAAsC;EAEjD;EACA;EACA;EACA;GACA;;;;cC1RW,gBAAa;;cAIb,iBAAc;;UAGV;;EAEhB;;EAEA;;;;;;;;;;;;;;;;;;cAmBY,kBAAe,kBAAoB,qBAAqB;;;;;;;cCzBxD,2BAAyB;UAsBrB;EAChB;EACA;EACA;;;;;;;;;;;;;cAoBY,8BAA2B;EACvC;EACA;EACA;MACG;;;;;;;cA6CS,mCAAgC,YAChC,iBAAe,iBAEzB;;;;;;;;;;;;;cCpFU,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;;cA4CU,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"}