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