@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 +161 -0
- package/dist/build/index.d.ts +76 -40
- package/dist/build/index.d.ts.map +1 -1
- package/dist/build/index.js +54 -108
- package/dist/build/index.js.map +1 -1
- package/dist/index.d.ts +149 -121
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +277 -233
- package/dist/index.js.map +1 -1
- package/package.json +16 -7
- package/src/attachments.ts +67 -0
- package/src/build/address.ts +64 -0
- package/src/build/attachment.ts +33 -0
- package/src/build/identifiers.ts +253 -0
- package/src/build/index.ts +69 -0
- package/src/build/numeric.ts +41 -0
- package/src/build/party.ts +127 -0
- package/src/build/tax-category.ts +152 -0
- package/src/build/tax-totals.ts +143 -0
- package/src/build/ubl/constants.ts +30 -0
- package/src/build/ubl/serialize.ts +258 -0
- package/src/build/ubl/types.ts +179 -0
- package/src/build/utils.ts +6 -0
- package/src/build/xml.ts +84 -0
- package/src/errors.ts +15 -0
- package/src/index.ts +40 -0
- package/src/mlr.ts +156 -0
- package/src/normalize.ts +407 -0
- package/src/parser.ts +596 -0
- package/src/types.ts +234 -0
- package/src/xml-dom.ts +37 -0
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.
|
package/dist/build/index.d.ts
CHANGED
|
@@ -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
|
|
27
|
-
*
|
|
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
|
-
*
|
|
201
|
-
*
|
|
202
|
-
*
|
|
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
|
|
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 =
|
|
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:
|
|
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) =>
|
|
334
|
+
declare const normalizeCompanyNumberForCountry: (countryCode: string | null | undefined, companyNumber: string | null | undefined) => any;
|
|
312
335
|
/**
|
|
313
|
-
*
|
|
314
|
-
* (`cac:PartyLegalEntity/cbc:CompanyID/@schemeID`).
|
|
315
|
-
*
|
|
316
|
-
*
|
|
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:
|
|
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/
|
|
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"}
|