@financica/ubl 0.15.1 → 0.16.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 ADDED
@@ -0,0 +1,161 @@
1
+ # Changelog
2
+
3
+ ## 0.16.0
4
+
5
+ ### Changed
6
+
7
+ - **BREAKING: `SupplierVatStatus` is a string union.** `1 | 2 | 3` becomes `"subject" | "not_subject" | "small_business"`; the numbers were Scrada's wire encoding leaking into a generic model. Callers that hold the Scrada code map it at their own boundary.
8
+ - **EAS schemes come from `@financica/peppol` instead of a private copy.** `resolveVatEndpoint` and `resolveCompanyIdScheme` resolve through `getPeppolIdentifierSchemes`, so the three hand-copied tables are one. Routing changes for two countries whose verified profile disagreed with the old copy: Swedish VAT numbers now resolve to `9955` and Italian to `0211` (previously null). Requires `@financica/peppol` ≥ 0.8.0.
9
+ - **BREAKING: parse errors throw `UblParseError`; `null` means "not a UBL invoice".** `parseUblInvoice` returns `null` only when well-formed XML has a root other than a UBL `Invoice`/`CreditNote`; malformed XML and documents missing a mandatory element (`cbc:ID`, `cbc:IssueDate`, `cbc:DocumentCurrencyCode`, a line `cbc:ID`) throw the new `UblParseError` (exported from the root, `cause` set when wrapping). `parsePeppolMessageLevelResponse`, `extractUblEmbeddedAttachments` and `normalizeUblResponse` throw the same class instead of a generic `Error`; `isPeppolMessageLevelResponse` stays a non-throwing sniff.
10
+ - **BREAKING: the parsed model has no sentinel values.** A field the document omits is an absent key instead of `""`/`0`/`"Unknown"`: `UblAddress` (`street`, `city`, `postalZone`, `countryCode`), `UblParty.name`, `UblLine` (`description`, `quantity`, `unitCode`, `unitPrice`, `lineExtensionAmount`), `UblTaxSubtotal` (`taxableAmount`, `taxAmount`, `taxPercent`), every `UblMonetaryTotal` amount, `UblAllowanceCharge.amount`, `UblPaymentMeans.code`, `UblAttachment.id`, `UblDocumentReference.id`, `UblItemProperty.value` and `UblEmbeddedAttachment.id` are now optional, and `PeppolMessageLevelResponse` fields are `?: string` instead of `string | null`. `seller`, `buyer`, `monetaryTotal`, `lines` and `taxSubtotals` are always present. `normalizeUblResponse` reports `null` where it previously reported a manufactured `0` (totals of a document without `LegalMonetaryTotal`, line quantity/price/amount the line does not state), and attachment `sizeBytes` is the exact padding-aware decoded size.
11
+ - **Build-side inputs are typed instead of `unknown`.** `extractCustomerTaxIdentifiers` takes `readonly CustomerTaxIdInput[] | null | undefined` (`{type, value}` pairs, the shape of Stripe's `customer_tax_ids`), and `normalizeAddress` / `UblSupplier.address` take the new `AddressInput` (Stripe `line1`/`postal_code`/`country` and legacy `street`/`zip_code`/`country_code` keys). Both new types are exported from `@financica/ubl/build`. Runtime behaviour is unchanged; callers that passed arbitrary values must now pass the documented shape (or `null`). `listPeppolReceiverIdentifierCandidates` accepts `Partial<CustomerTaxIdentifiers>`, which is the same shape it took before.
12
+
13
+ ### Added
14
+
15
+ - **`coerceLinesForSupplierVatStatus(lines, vatStatus, supplierCountryCode?)`** — the "seller does not charge VAT → every line is `E`/0% with a BT-120 reason" rule now lives here instead of inside the Stripe adapter, so every adapter gets it. The Belgian Article 56bis text is picked by supplier country; other countries get a generic reason.
16
+
17
+ ## 0.15.1
18
+
19
+ ### Fixed
20
+
21
+ - **`extractCustomerTaxIdentifiers` no longer drops non-VAT registration numbers.** An entry was classified by substring of its type (`vat`, `tax`, `peppol`, `gln`), so `ca_gst_hst`, `au_abn`, `us_ein`, `ch_uid` and most of the Stripe taxonomy vanished and a seller with only such an id failed the identifier check. Any other typed entry is now the registration number (BT-30).
22
+
23
+ ## 0.13.0
24
+
25
+ ### Added
26
+
27
+ - **Service periods, end to end.** `UblLine.invoicePeriod` carries a line's own `cac:InvoicePeriod` (BT-134/BT-135), which the parser previously discarded; `normalizeUblResponse` promotes both the document period (BT-73/BT-74) and each line's to first-class `period_start` / `period_end` DTO fields, so consumers no longer have to dig the document one out of `extra.invoice_period` and had no way at all to reach the line ones. The serializer emits `cac:InvoicePeriod` from `UblDocument.invoicePeriod` and `UblLine.invoicePeriod`, at the positions UBL's element sequence requires (after `cbc:BuyerReference` on the document, after `cbc:LineExtensionAmount` on a line). A period with neither bound set is omitted rather than emitted empty, which would fail BR-CO-19.
28
+
29
+ ### Fixed
30
+
31
+ - **A line's period is no longer reported as the document's.** The document-level lookup was a descendant search, so on an invoice that states a period only per line — the normal shape for a subscription bill with prorations — the first line's period surfaced as the whole document's. Both lookups now read direct children only.
32
+
33
+ ## 0.12.0
34
+
35
+ ### Added
36
+
37
+ - **`rounding_total` on the normalized DTO**: `normalizeUblResponse` now surfaces `cbc:PayableRoundingAmount` (BT-114). The parser has always read it into `UblMonetaryTotal`; it simply never reached the DTO, so consumers could not tell a cash-rounded payable from an unexplained gap.
38
+
39
+ ### Fixed
40
+
41
+ - **A rounded payable is no longer mistaken for a prepayment.** With no declared `cbc:PrepaidAmount`, `amount_paid` was inferred from any `TaxInclusiveAmount > PayableAmount` gap — but under BR-CO-16 a rounding amount is exactly such a gap by design. An invoice rounded _down_ (27.17 → 27.15, the Belgian nearest-0.05 cash rule) imported as 0.02 already paid, reporting an untouched invoice as partially settled; one rounded _up_ left the total and the amount due disagreeing with nothing to explain it. The rounding term is now removed before the inference, and the result is rounded to cents before the sign test so the float residue of undoing it cannot pass as a sub-cent prepayment. A declared `PrepaidAmount` is still authoritative and is untouched.
42
+
43
+ ## 0.11.0
44
+
45
+ ### Added
46
+
47
+ - **`deriveUnitPrice` and `UblLine.baseQuantity` (BT-149)**: the serializer now emits `cbc:BaseQuantity` inside `cac:Price`, carrying the quantity's unit code as PEPPOL-EN16931-R130 requires.
48
+
49
+ ### Fixed
50
+
51
+ - **Line prices no longer violate PEPPOL-EN16931-R120.** A line's net price was derived as `net ÷ quantity` rounded to cents, which breaks the rule whenever the division doesn't land on a cent: 940.00 over 14 units gives 67.142857…, and 14 × 67.14 = 939.96 — 0.04 out against a 0.02 tolerance, rejected as a _fatal_ validation error, so the document is never transmitted. `deriveUnitPrice` keeps the cent-rounded unit price only when it reproduces the net exactly, and otherwise prices the line as a whole via BT-149 (`priceAmount` = the net, `baseQuantity` = the quantity). That is exact at any magnitude, rather than merely within tolerance — the residual of a rounded unit price grows with quantity and would eventually breach 0.02 at any fixed precision.
52
+ - **`reconcileLinesToExclTotal` re-derives the price after adjusting a line's net.** It previously re-divided at cent precision, reintroducing the same R120 violation on the very line it had just corrected. It now routes through `deriveUnitPrice` and clears a stale `baseQuantity` when the adjusted net divides evenly.
53
+
54
+ ## 0.10.0
55
+
56
+ ### Added
57
+
58
+ - **Prepayment and rounding on the build side**: `UblMonetaryTotal` gains optional `prepaidAmount` (BT-113, gross/VAT-inclusive) and `payableRoundingAmount` (BT-114), and the serializer emits `cbc:PrepaidAmount` / `cbc:PayableRoundingAmount` in UBL sequence order (before `cbc:PayableAmount`). Both are omitted when absent or zero.
59
+ - **`buildTaxTotals` derives `payableAmount` per BR-CO-16**: an optional second argument (`BuildTaxTotalsOptions`) supplies the prepaid and rounding terms, and BT-115 is computed as `taxInclusiveAmount - prepaidAmount + payableRoundingAmount` rather than hardwired to the gross total. Documents for already-settled invoices — credit notes against paid invoices in particular — no longer present their full gross total as outstanding, which was a double-payment risk. The result is not clamped, so an overpayment surfaces as a negative payable amount instead of being silently hidden. Existing single-argument call sites are unchanged.
60
+
61
+ ## 0.9.0
62
+
63
+ ### Added
64
+
65
+ - **Tax categories K and G**: `taxCategoryFromReasonOrRate` maps intra-community supply to category `K` and export outside the EU to category `G`, both zero-rated with the required EN 16931 exemption reason. Previously both fell through to the generic `E` (exempt).
66
+
67
+ ### Changed
68
+
69
+ - **Toolchain migrated to bun + oxc**: oxlint replaces ESLint, oxfmt replaces Prettier, and tsdown replaces tsup for the dual-entry (`.` and `./build`) build. TypeScript upgraded to 7.0; `bun.lock` replaces `package-lock.json`.
70
+ - **`@xmldom/xmldom` upgraded to 0.9**: 0.9 drops the ambient DOM lib reference and exports its own DOM types, so the parser and MLR reader now import `Element`/`Document` from the package and read `globalThis.DOMParser` through a typed cast. The isomorphic design is unchanged (native browser `DOMParser` preferred, xmldom as the Node fallback).
71
+
72
+ ### Fixed
73
+
74
+ - **Null `documentElement` guard in `parseUblInvoice`**: xmldom 0.9 correctly types `Document.documentElement` as nullable; the missing guard is now in place (`parsePeppolMessageLevelResponse` already had one).
75
+
76
+ ## 0.8.0
77
+
78
+ ### Added
79
+
80
+ - **`extractUblEmbeddedAttachments` and `isPdfLikeAttachment`**: embedded-attachment extraction (base64 content, approximate decoded size, PDF sniffing) moves into the library instead of being reimplemented on top of `parseUblInvoice` by callers. References carrying only an external URI are skipped.
81
+
82
+ ## 0.7.0
83
+
84
+ ### Added
85
+
86
+ - **`buildCustomerParty`**: the buyer-party builder is promoted out of `@financica/stripe-ubl` into the shared build core so every X→UBL adapter resolves the Peppol `EndpointID` identically — explicit Peppol ID → GLN (`0088`) → VAT EAS scheme (e.g. BE → `9925`). A customer known only by VAT number now gets a routable endpoint instead of `null`.
87
+
88
+ ## 0.6.0
89
+
90
+ ### Added
91
+
92
+ - **`resolveVatEndpoint` and qualified receiver candidates**: `listPeppolReceiverIdentifierCandidates` previously returned bare values (e.g. a VAT number `BE0206582284`), but a participant lookup needs a fully-qualified `scheme:value` identifier — fed through `parsePeppolEndpoint` a bare value has no `:` to split on and yielded `null`, so a registered recipient could not be resolved. Candidates are now emitted qualified and in priority order: explicit Peppol ID, GLN (`0088`), VAT (country scheme), the Belgian enterprise-number fallback (`0208`), then a generic tax number. Backed by a country → VAT EAS scheme table from the Peppol Code Lists (Participant Identifier Schemes, BIS Billing 3.0, Nov 2025). Countries that address by organisation number rather than VAT (SE/DK/NO) are intentionally absent.
93
+
94
+ ### Changed
95
+
96
+ - Repository moved to `github.com/financica/ubl-ts`; package metadata and README updated to match.
97
+
98
+ ### Documentation
99
+
100
+ - The README documents the build/serialize API with a complete, type-checked `UblDocument` example alongside the existing parse-side usage.
101
+
102
+ ## 0.5.0
103
+
104
+ ### Added
105
+
106
+ - **UBL build core at `@financica/ubl/build`**: a generic Peppol BIS Billing 3.0 document model, serializer (`serializeUblDocument`), and party/tax/identifier/attachment builders. Extracted from `@financica/stripe-ubl` so any X→UBL adapter shares one core. The build-side types live under the subpath so they do not collide with the parse-side types exported from the package root.
107
+
108
+ ## 0.4.0
109
+
110
+ ### Added
111
+
112
+ - **Peppol Message Level Response parser**: `parsePeppolMessageLevelResponse` and `isPeppolMessageLevelResponse`, plus the `PEPPOL_MLR_*` document-type and process constants. Parses a UBL `ApplicationResponse` (the Peppol transport-level ack), unwrapping an SBDH envelope when present, using the same XXE-safe approach as the invoice parser.
113
+
114
+ ## 0.3.2
115
+
116
+ ### Fixed
117
+
118
+ - **Unit price now divides PriceAmount by BaseQuantity**: When `cac:Price/cbc:BaseQuantity` is present and greater than 1, the effective unit price (BT-146 / BT-149) was previously reported as the raw `PriceAmount`, overstating per-unit cost on invoices that price by a multi-unit basis (e.g. €75.00 per 1.5 hours now correctly reports `unitPrice: 50`, not `75`).
119
+
120
+ ## 0.3.1
121
+
122
+ ### Fixed
123
+
124
+ - **`Price/AllowanceCharge` line discounts**: the parser only collected `AllowanceCharge` elements that were direct children of `InvoiceLine`. UBL also allows `Price/AllowanceCharge` for per-unit discounts (e.g. a 100% discount on a subscription); these were silently ignored, leaving `discount_amount` null. They are now merged into the line's `allowanceCharges` and reflected in `discountAmount`.
125
+
126
+ ## 0.3.0
127
+
128
+ ### Added
129
+
130
+ - **Real-world Peppol invoice features** seen in telco invoices: `AdditionalDocumentReference` without an attachment (text-only references such as terms & conditions), `ExternalReference/URI` for externally hosted attachments, `PaymentMandate/ID` for SEPA Direct Debit mandates, `AdditionalItemProperty` on lines as key-value metadata, multiple `PartyIdentification` elements with scheme IDs, and the `schemeID` attribute on `PartyLegalEntity/CompanyID`.
131
+
132
+ ### Changed
133
+
134
+ - **Package renamed** from `@ingram-tech/ubl` to `@financica/ubl`. 0.3.0 was published under both names — as `@ingram-tech/ubl` on 2026-03-07 (tagged `v0.3.0`), then republished unchanged apart from the rename as `@financica/ubl` on 2026-04-02. `@financica/ubl` starts at 0.3.0; 0.1.0 through 0.2.0 exist only under the old name.
135
+
136
+ ## 0.2.0
137
+
138
+ ### Added
139
+
140
+ - **CreditNote type code support**: `invoiceTypeCode` now correctly reads `cbc:CreditNoteTypeCode` for CreditNote documents (previously only read `cbc:InvoiceTypeCode`, which is absent on credit notes).
141
+ - **Billing reference parsing**: New `UblBillingReference` type and `billingReference` field on `UblInvoice`. Extracts the original invoice ID and issue date from `cac:BillingReference/cac:InvoiceDocumentReference` -- essential for credit notes that reference the invoice being corrected.
142
+ - **DTO billing reference**: `normalizeUblResponse()` now includes `billing_reference` in the `extra` object with `invoice_id` and `invoice_issue_date`.
143
+
144
+ ## 0.1.1
145
+
146
+ Published as `@ingram-tech/ubl` from an uncommitted version bump, so no commit
147
+ carries this version and it has no release tag.
148
+
149
+ ### Changed
150
+
151
+ - Added `prepack` script to ensure build runs before publish. (Committed later, with 0.2.0.)
152
+
153
+ ## 0.1.0
154
+
155
+ ### Added
156
+
157
+ - Initial release.
158
+ - `parseUblInvoice(xml)` -- parse UBL 2.1 Invoice and CreditNote XML into typed objects.
159
+ - `normalizeUblResponse(xml, documentId)` -- normalize parsed UBL into a flat `InvoiceExtractionDTO`.
160
+ - `parseUblInvoiceDocument({ bytes, documentId, mimeType })` -- parse from raw bytes with BOM handling.
161
+ - Full type exports for all UBL structures.
@@ -23,8 +23,8 @@ declare const NS_CBC = "urn:oasis:names:specification:ubl:schema:xsd:CommonBasic
23
23
  /**
24
24
  * A vendor-neutral model of a Peppol BIS Billing 3.0 document.
25
25
  *
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.
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
28
  * It is deliberately a thin, construction-oriented mirror of the UBL fields we
29
29
  * populate — not a full UBL object graph.
30
30
  */
@@ -80,7 +80,7 @@ interface UblTaxCategory {
80
80
  id: string;
81
81
  percent: number;
82
82
  /** Required by EN 16931 (BR-E-10/BR-AE-10/…) for non-`S`/`Z` categories. */
83
- exemptionReason?: string | null;
83
+ exemptionReason?: string | null | undefined;
84
84
  }
85
85
  interface UblLine {
86
86
  /** `cbc:ID` (BT-126) — line identifier. */
@@ -101,7 +101,7 @@ interface UblLine {
101
101
  * cents, so `quantity × (priceAmount ÷ baseQuantity)` reproduces the line
102
102
  * net exactly (PEPPOL-EN16931-R120); see `deriveUnitPrice`.
103
103
  */
104
- baseQuantity?: number;
104
+ baseQuantity?: number | undefined;
105
105
  /** `cac:InvoicePeriod` (BT-134/BT-135) — the line's own service period. */
106
106
  invoicePeriod?: UblPeriod | null;
107
107
  taxCategory: UblTaxCategory;
@@ -192,19 +192,54 @@ interface UblDocument {
192
192
  /** Serialize a {@link UblDocument} into a Peppol BIS Billing 3.0 XML string. */
193
193
  declare const serializeUblDocument: (doc: UblDocument) => string;
194
194
  //#endregion
195
+ //#region src/build/address.d.ts
196
+ /**
197
+ * A free-form postal address as accepted by {@link normalizeAddress}.
198
+ *
199
+ * Both the Stripe shape (`line1`, `postal_code`, `country`, `state`) and the
200
+ * legacy/internal shape (`street`, `zip_code`, `country_code`,
201
+ * `country_subentity`) are accepted; when both keys are present the Stripe
202
+ * one wins.
203
+ */
204
+ interface AddressInput {
205
+ line1?: string | null;
206
+ line2?: string | null;
207
+ street?: string | null;
208
+ city?: string | null;
209
+ postal_code?: string | null;
210
+ zip_code?: string | null;
211
+ state?: string | null;
212
+ country_subentity?: string | null;
213
+ country?: string | null;
214
+ country_code?: string | null;
215
+ }
216
+ /**
217
+ * Normalize a free-form address (Stripe shape, custom shape, or an internal
218
+ * shape) into a {@link UblAddress}.
219
+ *
220
+ * Accepts both `line1`/`postal_code`/`country` (Stripe) and `street`/`zip_code`
221
+ * (legacy/internal) keys. Falls back to `fallbackCountryCode` when the address
222
+ * has no country, but never silently substitutes a caller's country — pass
223
+ * `null` when "no country" is the right answer.
224
+ */
225
+ declare const normalizeAddress: (address: AddressInput | null | undefined, fallbackCountryCode: string | null, fallbackLine?: string | null) => UblAddress;
226
+ //#endregion
195
227
  //#region src/build/party.d.ts
196
228
  /**
197
229
  * Supplier (seller) VAT status. Drives how zero-VAT lines are reported when the
198
230
  * seller does not charge VAT:
199
231
  *
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).
232
+ * - `subject` — subject to VAT (the normal case): line categories come from
233
+ * the data.
234
+ * - `not_subject` — not subject to VAT.
235
+ * - `small_business` — small business / franchise exemption (e.g. Belgian
236
+ * Article 56bis).
203
237
  *
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.
238
+ * For the last two, `coerceLinesForSupplierVatStatus` (tax-category.ts) turns
239
+ * every line into a non-charging exempt category so no VAT is reported.
240
+ * Providers that encode this numerically (Scrada: 1/2/3) map at their boundary.
206
241
  */
207
- type SupplierVatStatus = 1 | 2 | 3;
242
+ type SupplierVatStatus = "subject" | "not_subject" | "small_business";
208
243
  /**
209
244
  * Caller-provided supplier data, normalized into a stable shape.
210
245
  *
@@ -220,7 +255,7 @@ interface UblSupplier {
220
255
  * Free-form address. Stripe-style fields (`line1`, `postal_code`, `country`)
221
256
  * and legacy/internal fields (`street`, `zip_code`) are both accepted.
222
257
  */
223
- address: unknown;
258
+ address: AddressInput | null;
224
259
  /** Country-specific company/registration number (e.g. BE enterprise number). */
225
260
  companyNumber?: string | null;
226
261
  /** VAT number with country prefix (e.g. `"BE0793904121"`). */
@@ -273,18 +308,6 @@ interface UblCustomer {
273
308
  */
274
309
  declare const buildCustomerParty: (customer: UblCustomer, endpointOverride?: UblEndpoint | null) => UblParty;
275
310
  //#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
311
  //#region src/build/attachment.d.ts
289
312
  /**
290
313
  * Build a UBL embedded-document attachment (BG-24) from raw bytes — e.g. the
@@ -308,14 +331,12 @@ declare const sanitizeUblDocumentForAudit: (doc: UblDocument) => UblDocument;
308
331
  * Strip whitespace/punctuation from a country-specific company number.
309
332
  * For Belgium, also strips an optional `BE` prefix.
310
333
  */
311
- declare const normalizeCompanyNumberForCountry: (countryCode: string | null | undefined, companyNumber: string | null | undefined) => string;
334
+ declare const normalizeCompanyNumberForCountry: (countryCode: string | null | undefined, companyNumber: string | null | undefined) => any;
312
335
  /**
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)
336
+ * Peppol/ISO 6523 ICD scheme for a legal registration number
337
+ * (`cac:PartyLegalEntity/cbc:CompanyID/@schemeID`), e.g. BE → `0208`
338
+ * (enterprise number), NL → `0106` (KvK), FR → `0002` (SIRENE). The table is
339
+ * `@financica/peppol`'s country profiles.
319
340
  *
320
341
  * Falls back to inspecting the number's country prefix (e.g. `BE0793904121`).
321
342
  * Returns `null` when the scheme can't be determined, in which case the
@@ -340,13 +361,17 @@ declare const buildCompanyId: (params: {
340
361
  *
341
362
  * `BE0206582284` → `{ scheme: "9925", value: "BE0206582284" }`
342
363
  *
364
+ * The scheme comes from `@financica/peppol`'s country resolution, so countries
365
+ * that route on their registry number alone (Norway, Denmark) yield `null`
366
+ * here — their VAT number is not a Peppol participant identifier.
367
+ *
343
368
  * The value keeps its country prefix, matching how participants register (the
344
369
  * Peppol directory lists this party as `9925:be0206582284`). Returns `null`
345
370
  * when the country has no VAT EAS scheme or the input is empty.
346
371
  */
347
372
  declare const resolveVatEndpoint: (params: {
348
373
  vatNumber: string | null | undefined;
349
- countryCode?: string | null;
374
+ countryCode?: string | null | undefined;
350
375
  }) => UblEndpoint | null;
351
376
  /**
352
377
  * Parse a Peppol participant identifier into a {@link UblEndpoint}.
@@ -362,6 +387,15 @@ interface CustomerTaxIdentifiers {
362
387
  taxNumber: string | null;
363
388
  vatNumber: string | null;
364
389
  }
390
+ /**
391
+ * One customer tax identifier as stored by Stripe (`customer_tax_ids[]`) or an
392
+ * equivalent `{type, value}` pair. `type` is a Stripe tax-ID type such as
393
+ * `eu_vat`, or a custom type such as `peppol_id`; blank entries are skipped.
394
+ */
395
+ interface CustomerTaxIdInput {
396
+ type: string | null | undefined;
397
+ value: string | null | undefined;
398
+ }
365
399
  /**
366
400
  * Pick the first usable Peppol identifier, GLN, VAT number, and tax number
367
401
  * from a Stripe-style `customer_tax_ids` array (`[{type, value}, …]`).
@@ -369,7 +403,7 @@ interface CustomerTaxIdentifiers {
369
403
  * Stripe stores VAT numbers under types like `eu_vat`, `gb_vat`, etc.
370
404
  * Peppol IDs are typically stored as a custom `peppol_id` type.
371
405
  */
372
- declare const extractCustomerTaxIdentifiers: (taxIds: unknown) => CustomerTaxIdentifiers;
406
+ declare const extractCustomerTaxIdentifiers: (taxIds: readonly CustomerTaxIdInput[] | null | undefined) => CustomerTaxIdentifiers;
373
407
  /**
374
408
  * Build the fully-qualified Peppol participant identifiers (`scheme:value`) a
375
409
  * receiver lookup will accept, in priority order, de-duplicated.
@@ -389,12 +423,7 @@ declare const extractCustomerTaxIdentifiers: (taxIds: unknown) => CustomerTaxIde
389
423
  * `countryCode` (the customer's country, when known) disambiguates schemes for
390
424
  * identifiers that don't carry a country prefix (GLN, plain tax numbers).
391
425
  */
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[];
426
+ declare const listPeppolReceiverIdentifierCandidates: (customer: Partial<CustomerTaxIdentifiers>, countryCode?: string | null) => string[];
398
427
  //#endregion
399
428
  //#region src/build/numeric.d.ts
400
429
  /** Round a number to 2 decimal places (cents). */
@@ -406,7 +435,7 @@ interface UnitPrice {
406
435
  /** `cbc:PriceAmount` (BT-146). */
407
436
  priceAmount: number;
408
437
  /** `cbc:BaseQuantity` (BT-149) — the units `priceAmount` covers. Omitted = 1. */
409
- baseQuantity?: number;
438
+ baseQuantity?: number | undefined;
410
439
  }
411
440
  /**
412
441
  * Derive the `cac:Price` for a line whose net total is authoritative.
@@ -460,6 +489,13 @@ declare const taxCategoryFromReasonOrRate: (params: {
460
489
  * otherwise the rate decides standard (`S`) vs zero-rated (`Z`).
461
490
  */
462
491
  declare const resolveTaxCategoryFromTaxAmounts: (taxAmounts: TaxAmountInfo[], rate: number) => UblTaxCategory;
492
+ /**
493
+ * When the supplier does not charge VAT, coerce every line to a non-charging
494
+ * exempt category (`E`, 0%) with the appropriate BT-120 reason, so the document
495
+ * reports no VAT regardless of what the upstream line tax data implied. Lines
496
+ * are returned untouched for a `subject` supplier.
497
+ */
498
+ declare const coerceLinesForSupplierVatStatus: (lines: UblLine[], vatStatus: SupplierVatStatus, supplierCountryCode?: string | null) => UblLine[];
463
499
  //#endregion
464
500
  //#region src/build/tax-totals.d.ts
465
501
  /**
@@ -536,5 +572,5 @@ declare const el: (name: string, attrs?: XmlAttrs | null, content?: string | num
536
572
  /** Serialize a root element into a UTF-8 XML document string. */
537
573
  declare const serializeDocument: (root: XmlElement) => string;
538
574
  //#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 };
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 };
540
576
  //# 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/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"}