@financica/ubl 0.15.1 → 0.17.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +168 -0
- package/README.md +20 -25
- package/dist/build/index.d.ts +122 -221
- package/dist/build/index.d.ts.map +1 -1
- package/dist/build/index.js +277 -232
- 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 +31 -225
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +327 -260
- 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 +16 -7
- package/src/attachments.ts +67 -0
- package/src/build/address.ts +63 -0
- package/src/build/attachment.ts +37 -0
- package/src/build/identifiers.ts +253 -0
- package/src/build/index.ts +79 -0
- package/src/build/numeric.ts +47 -0
- package/src/build/party.ts +129 -0
- package/src/build/tax-category.ts +153 -0
- package/src/build/tax-totals.ts +154 -0
- package/src/build/ubl/constants.ts +30 -0
- package/src/build/ubl/serialize.ts +437 -0
- package/src/build/utils.ts +14 -0
- package/src/build/xml.ts +84 -0
- package/src/errors.ts +31 -0
- package/src/index.ts +44 -0
- package/src/mlr.ts +156 -0
- package/src/normalize.ts +408 -0
- package/src/parser.ts +651 -0
- package/src/types.ts +398 -0
- package/src/xml-dom.ts +37 -0
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,192 +20,76 @@ declare const NS_CREDIT_NOTE = "urn:oasis:names:specification:ubl:schema:xsd:Cre
|
|
|
19
20
|
declare const NS_CAC = "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2";
|
|
20
21
|
declare const NS_CBC = "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2";
|
|
21
22
|
//#endregion
|
|
22
|
-
//#region src/build/ubl/
|
|
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.
|
|
26
|
+
*
|
|
27
|
+
* Emits the subset of the model a Peppol BIS Billing 3.0 document needs:
|
|
28
|
+
* header (`customizationId`, `profileId` and `invoiceTypeCode` default to the
|
|
29
|
+
* BIS values), note, buyer reference, invoice period, billing reference,
|
|
30
|
+
* attachments, parties, payment terms, VAT breakdown, monetary totals and
|
|
31
|
+
* lines with their price and classified VAT category. Payment means,
|
|
32
|
+
* allowances/charges, delivery and the document references are not emitted.
|
|
25
33
|
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
34
|
+
* @throws {UblBuildError} when a field EN 16931 / Peppol BIS makes mandatory is
|
|
35
|
+
* missing: document id, issue date, currency, seller and buyer name, an
|
|
36
|
+
* endpoint without a scheme, at least one line, per line the quantity, unit
|
|
37
|
+
* code, unit price, net amount and VAT category (id, plus the rate unless the
|
|
38
|
+
* category is `O`), the total VAT amount, the four monetary totals, and for an
|
|
39
|
+
* embedded attachment its filename, MIME code and content.
|
|
30
40
|
*/
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
/** `cbc:CityName` (BT-37). */
|
|
37
|
-
city: string | null;
|
|
38
|
-
/** `cbc:PostalZone` (BT-38). */
|
|
39
|
-
postalZone: string | null;
|
|
40
|
-
/** `cbc:CountrySubentity` (BT-39). */
|
|
41
|
-
countrySubentity: string | null;
|
|
42
|
-
/** `cac:Country/cbc:IdentificationCode` (BT-40) — ISO 3166-1 alpha-2. */
|
|
43
|
-
countryCode: string | null;
|
|
44
|
-
}
|
|
45
|
-
/** Peppol participant identifier, e.g. scheme `0208`, value `0800279001`. */
|
|
46
|
-
interface UblEndpoint {
|
|
47
|
-
scheme: string;
|
|
48
|
-
value: string;
|
|
49
|
-
}
|
|
50
|
-
/** Legal registration identifier, e.g. a Belgian enterprise number. */
|
|
51
|
-
interface UblCompanyId {
|
|
52
|
-
value: string;
|
|
53
|
-
/** ICD scheme (e.g. `0208` for the Belgian CBE), when known. */
|
|
54
|
-
scheme?: string | null;
|
|
55
|
-
}
|
|
56
|
-
interface UblParty {
|
|
57
|
-
/** `cbc:EndpointID` (BT-49/BT-34) — the Peppol routing identifier. */
|
|
58
|
-
endpoint: UblEndpoint | null;
|
|
59
|
-
/** `cac:PartyName/cbc:Name` (BT-27/BT-44). */
|
|
60
|
-
name: string;
|
|
61
|
-
address: UblAddress;
|
|
62
|
-
/** `cac:PartyTaxScheme/cbc:CompanyID` with `VAT` scheme (BT-31/BT-48). */
|
|
63
|
-
vatNumber: string | null;
|
|
64
|
-
/** `cac:PartyLegalEntity/cbc:RegistrationName` (BT-27/BT-44). Defaults to `name`. */
|
|
65
|
-
legalName: string | null;
|
|
66
|
-
/** `cac:PartyLegalEntity/cbc:CompanyID` (BT-30/BT-47). */
|
|
67
|
-
companyId: UblCompanyId | null;
|
|
68
|
-
}
|
|
41
|
+
declare const serializeUblInvoice: (doc: UblInvoice) => string;
|
|
42
|
+
/** Alias of {@link serializeUblInvoice}, kept under the historical name. */
|
|
43
|
+
declare const serializeUblDocument: typeof serializeUblInvoice;
|
|
44
|
+
//#endregion
|
|
45
|
+
//#region src/build/address.d.ts
|
|
69
46
|
/**
|
|
70
|
-
*
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
* - `K` Intra-community supply
|
|
77
|
-
* - `G` Export outside the EU
|
|
47
|
+
* A free-form postal address as accepted by {@link normalizeAddress}.
|
|
48
|
+
*
|
|
49
|
+
* Both the Stripe shape (`line1`, `postal_code`, `country`, `state`) and the
|
|
50
|
+
* legacy/internal shape (`street`, `zip_code`, `country_code`,
|
|
51
|
+
* `country_subentity`) are accepted; when both keys are present the Stripe
|
|
52
|
+
* one wins.
|
|
78
53
|
*/
|
|
79
|
-
interface
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
/** `cbc:InvoicedQuantity` / `cbc:CreditedQuantity` (BT-129). */
|
|
91
|
-
quantity: number;
|
|
92
|
-
/** UN/ECE Rec 20 unit code (BT-130). */
|
|
93
|
-
unitCode: string;
|
|
94
|
-
/** `cbc:LineExtensionAmount` (BT-131) — net of VAT, after line discounts. */
|
|
95
|
-
lineExtensionAmount: number;
|
|
96
|
-
/** `cac:Price/cbc:PriceAmount` (BT-146) — net unit price. */
|
|
97
|
-
priceAmount: number;
|
|
98
|
-
/**
|
|
99
|
-
* `cac:Price/cbc:BaseQuantity` (BT-149) — the number of units `priceAmount`
|
|
100
|
-
* covers. Omitted means 1. Set it when the net doesn't divide evenly into
|
|
101
|
-
* cents, so `quantity × (priceAmount ÷ baseQuantity)` reproduces the line
|
|
102
|
-
* net exactly (PEPPOL-EN16931-R120); see `deriveUnitPrice`.
|
|
103
|
-
*/
|
|
104
|
-
baseQuantity?: number;
|
|
105
|
-
/** `cac:InvoicePeriod` (BT-134/BT-135) — the line's own service period. */
|
|
106
|
-
invoicePeriod?: UblPeriod | null;
|
|
107
|
-
taxCategory: UblTaxCategory;
|
|
108
|
-
}
|
|
109
|
-
interface UblTaxSubtotal {
|
|
110
|
-
/** `cbc:TaxableAmount` (BT-116). */
|
|
111
|
-
taxableAmount: number;
|
|
112
|
-
/** `cbc:TaxAmount` (BT-117). */
|
|
113
|
-
taxAmount: number;
|
|
114
|
-
category: UblTaxCategory;
|
|
115
|
-
}
|
|
116
|
-
interface UblTaxTotal {
|
|
117
|
-
/** `cbc:TaxAmount` (BT-110) — sum of subtotal tax amounts. */
|
|
118
|
-
taxAmount: number;
|
|
119
|
-
subtotals: UblTaxSubtotal[];
|
|
120
|
-
}
|
|
121
|
-
interface UblMonetaryTotal {
|
|
122
|
-
/** BT-106 — sum of line net amounts. */
|
|
123
|
-
lineExtensionAmount: number;
|
|
124
|
-
/** BT-109 — total without VAT. */
|
|
125
|
-
taxExclusiveAmount: number;
|
|
126
|
-
/** BT-112 — total with VAT. */
|
|
127
|
-
taxInclusiveAmount: number;
|
|
128
|
-
/**
|
|
129
|
-
* BT-113 — sum of amounts paid in advance. **Gross (VAT-inclusive)**, since
|
|
130
|
-
* BR-CO-16 subtracts it directly from BT-112. Omitted when absent or zero.
|
|
131
|
-
*/
|
|
132
|
-
prepaidAmount?: number;
|
|
133
|
-
/** BT-114 — rounding applied to the payable amount. Omitted when absent or zero. */
|
|
134
|
-
payableRoundingAmount?: number;
|
|
135
|
-
/**
|
|
136
|
-
* BT-115 — amount due for payment, i.e. the *outstanding* amount.
|
|
137
|
-
* BR-CO-16: `BT-115 = BT-112 − BT-113 + BT-114`.
|
|
138
|
-
*/
|
|
139
|
-
payableAmount: number;
|
|
140
|
-
}
|
|
141
|
-
/** An embedded supporting document (BG-24), e.g. the rendered PDF. */
|
|
142
|
-
interface UblAttachment {
|
|
143
|
-
/** `cac:AdditionalDocumentReference/cbc:ID` (BT-122). */
|
|
144
|
-
id: string;
|
|
145
|
-
/** `cbc:EmbeddedDocumentBinaryObject/@filename`. */
|
|
146
|
-
filename: string;
|
|
147
|
-
/** MIME type, e.g. `application/pdf`. */
|
|
148
|
-
mimeCode: string;
|
|
149
|
-
/** Base64-encoded document bytes. */
|
|
150
|
-
base64: string;
|
|
54
|
+
interface AddressInput {
|
|
55
|
+
line1?: string | null;
|
|
56
|
+
line2?: string | null;
|
|
57
|
+
street?: string | null;
|
|
58
|
+
city?: string | null;
|
|
59
|
+
postal_code?: string | null;
|
|
60
|
+
zip_code?: string | null;
|
|
61
|
+
state?: string | null;
|
|
62
|
+
country_subentity?: string | null;
|
|
63
|
+
country?: string | null;
|
|
64
|
+
country_code?: string | null;
|
|
151
65
|
}
|
|
152
66
|
/**
|
|
153
|
-
*
|
|
154
|
-
*
|
|
155
|
-
*
|
|
67
|
+
* Normalize a free-form address (Stripe shape, custom shape, or an internal
|
|
68
|
+
* shape) into a {@link UblAddress}. An absent part is an absent key.
|
|
69
|
+
*
|
|
70
|
+
* Accepts both `line1`/`postal_code`/`country` (Stripe) and `street`/`zip_code`
|
|
71
|
+
* (legacy/internal) keys. Falls back to `fallbackCountryCode` when the address
|
|
72
|
+
* has no country, but never silently substitutes a caller's country — pass
|
|
73
|
+
* `null` when "no country" is the right answer.
|
|
156
74
|
*/
|
|
157
|
-
|
|
158
|
-
/** `YYYY-MM-DD`. */
|
|
159
|
-
startDate: string | null;
|
|
160
|
-
/** `YYYY-MM-DD`, inclusive. */
|
|
161
|
-
endDate: string | null;
|
|
162
|
-
}
|
|
163
|
-
interface UblDocument {
|
|
164
|
-
documentType: "invoice" | "creditNote";
|
|
165
|
-
/** Invoice / credit note number (BT-1). */
|
|
166
|
-
id: string;
|
|
167
|
-
/** Issue date (BT-2), `YYYY-MM-DD`. */
|
|
168
|
-
issueDate: string;
|
|
169
|
-
/** Payment due date (BT-9). Invoices only. */
|
|
170
|
-
dueDate: string | null;
|
|
171
|
-
/** Free-text note (BT-22). */
|
|
172
|
-
note: string | null;
|
|
173
|
-
/** Payment terms note (BT-20, `cac:PaymentTerms/cbc:Note`). */
|
|
174
|
-
paymentTermsNote?: string | null;
|
|
175
|
-
/** Document currency (BT-5). */
|
|
176
|
-
currency: string;
|
|
177
|
-
/** Buyer reference (BT-10). */
|
|
178
|
-
buyerReference: string | null;
|
|
179
|
-
/** Invoicing period (BT-73/BT-74). */
|
|
180
|
-
invoicePeriod?: UblPeriod | null;
|
|
181
|
-
/** For credit notes: the referenced original invoice number (BT-25). */
|
|
182
|
-
precedingInvoiceId: string | null;
|
|
183
|
-
supplier: UblParty;
|
|
184
|
-
customer: UblParty;
|
|
185
|
-
lines: UblLine[];
|
|
186
|
-
taxTotal: UblTaxTotal;
|
|
187
|
-
monetaryTotal: UblMonetaryTotal;
|
|
188
|
-
attachments: UblAttachment[];
|
|
189
|
-
}
|
|
190
|
-
//#endregion
|
|
191
|
-
//#region src/build/ubl/serialize.d.ts
|
|
192
|
-
/** Serialize a {@link UblDocument} into a Peppol BIS Billing 3.0 XML string. */
|
|
193
|
-
declare const serializeUblDocument: (doc: UblDocument) => string;
|
|
75
|
+
declare const normalizeAddress: (address: AddressInput | null | undefined, fallbackCountryCode: string | null, fallbackLine?: string | null) => UblAddress;
|
|
194
76
|
//#endregion
|
|
195
77
|
//#region src/build/party.d.ts
|
|
196
78
|
/**
|
|
197
79
|
* Supplier (seller) VAT status. Drives how zero-VAT lines are reported when the
|
|
198
80
|
* seller does not charge VAT:
|
|
199
81
|
*
|
|
200
|
-
*
|
|
201
|
-
*
|
|
202
|
-
*
|
|
82
|
+
* - `subject` — subject to VAT (the normal case): line categories come from
|
|
83
|
+
* the data.
|
|
84
|
+
* - `not_subject` — not subject to VAT.
|
|
85
|
+
* - `small_business` — small business / franchise exemption (e.g. Belgian
|
|
86
|
+
* Article 56bis).
|
|
203
87
|
*
|
|
204
|
-
* For
|
|
205
|
-
* non-charging exempt category so no VAT is reported.
|
|
88
|
+
* For the last two, `coerceLinesForSupplierVatStatus` (tax-category.ts) turns
|
|
89
|
+
* every line into a non-charging exempt category so no VAT is reported.
|
|
90
|
+
* Providers that encode this numerically (Scrada: 1/2/3) map at their boundary.
|
|
206
91
|
*/
|
|
207
|
-
type SupplierVatStatus =
|
|
92
|
+
type SupplierVatStatus = "subject" | "not_subject" | "small_business";
|
|
208
93
|
/**
|
|
209
94
|
* Caller-provided supplier data, normalized into a stable shape.
|
|
210
95
|
*
|
|
@@ -220,7 +105,7 @@ interface UblSupplier {
|
|
|
220
105
|
* Free-form address. Stripe-style fields (`line1`, `postal_code`, `country`)
|
|
221
106
|
* and legacy/internal fields (`street`, `zip_code`) are both accepted.
|
|
222
107
|
*/
|
|
223
|
-
address:
|
|
108
|
+
address: AddressInput | null;
|
|
224
109
|
/** Country-specific company/registration number (e.g. BE enterprise number). */
|
|
225
110
|
companyNumber?: string | null;
|
|
226
111
|
/** VAT number with country prefix (e.g. `"BE0793904121"`). */
|
|
@@ -230,7 +115,7 @@ interface UblSupplier {
|
|
|
230
115
|
/** Peppol participant identifier in `scheme:value` form (e.g. `"0208:0793904121"`). */
|
|
231
116
|
peppolID?: string | null;
|
|
232
117
|
}
|
|
233
|
-
/** Convert a {@link UblSupplier} into the
|
|
118
|
+
/** Convert a {@link UblSupplier} into the seller party (`cac:AccountingSupplierParty`). */
|
|
234
119
|
declare const buildSupplierParty: (supplier: UblSupplier) => UblParty;
|
|
235
120
|
/**
|
|
236
121
|
* Caller-provided customer (buyer) data, normalized into a stable shape.
|
|
@@ -261,7 +146,7 @@ interface UblCustomer {
|
|
|
261
146
|
vatNumber?: string | null;
|
|
262
147
|
}
|
|
263
148
|
/**
|
|
264
|
-
* Convert a {@link UblCustomer} into the
|
|
149
|
+
* Convert a {@link UblCustomer} into the buyer party (`cac:AccountingCustomerParty`).
|
|
265
150
|
*
|
|
266
151
|
* The Peppol `EndpointID` (BT-49) — which routes the document — is resolved in
|
|
267
152
|
* priority order: an explicit `endpointOverride` (e.g. a confirmed-registered
|
|
@@ -273,18 +158,6 @@ interface UblCustomer {
|
|
|
273
158
|
*/
|
|
274
159
|
declare const buildCustomerParty: (customer: UblCustomer, endpointOverride?: UblEndpoint | null) => UblParty;
|
|
275
160
|
//#endregion
|
|
276
|
-
//#region src/build/address.d.ts
|
|
277
|
-
/**
|
|
278
|
-
* Normalize a free-form address (Stripe shape, custom shape, or an internal
|
|
279
|
-
* shape) into a {@link UblAddress}.
|
|
280
|
-
*
|
|
281
|
-
* Accepts both `line1`/`postal_code`/`country` (Stripe) and `street`/`zip_code`
|
|
282
|
-
* (legacy/internal) keys. Falls back to `fallbackCountryCode` when the address
|
|
283
|
-
* has no country, but never silently substitutes a caller's country — pass
|
|
284
|
-
* `null` when "no country" is the right answer.
|
|
285
|
-
*/
|
|
286
|
-
declare const normalizeAddress: (address: unknown, fallbackCountryCode: string | null, fallbackLine?: string | null) => UblAddress;
|
|
287
|
-
//#endregion
|
|
288
161
|
//#region src/build/attachment.d.ts
|
|
289
162
|
/**
|
|
290
163
|
* Build a UBL embedded-document attachment (BG-24) from raw bytes — e.g. the
|
|
@@ -299,69 +172,80 @@ declare const buildPdfAttachment: (params: {
|
|
|
299
172
|
}) => UblAttachment;
|
|
300
173
|
/**
|
|
301
174
|
* Replace each attachment's base64 payload with `[omitted]` plus a length, so a
|
|
302
|
-
* {@link
|
|
175
|
+
* {@link UblInvoice} is safe to log or persist for audit.
|
|
303
176
|
*/
|
|
304
|
-
declare const sanitizeUblDocumentForAudit: (doc:
|
|
177
|
+
declare const sanitizeUblDocumentForAudit: (doc: UblInvoice) => UblInvoice;
|
|
305
178
|
//#endregion
|
|
306
179
|
//#region src/build/identifiers.d.ts
|
|
307
180
|
/**
|
|
308
181
|
* Strip whitespace/punctuation from a country-specific company number.
|
|
309
182
|
* For Belgium, also strips an optional `BE` prefix.
|
|
310
183
|
*/
|
|
311
|
-
declare const normalizeCompanyNumberForCountry: (countryCode: string | null | undefined, companyNumber: string | null | undefined) =>
|
|
184
|
+
declare const normalizeCompanyNumberForCountry: (countryCode: string | null | undefined, companyNumber: string | null | undefined) => any;
|
|
312
185
|
/**
|
|
313
|
-
*
|
|
314
|
-
* (`cac:PartyLegalEntity/cbc:CompanyID/@schemeID`).
|
|
315
|
-
*
|
|
316
|
-
*
|
|
317
|
-
* NL → 0106 (Netherlands KvK)
|
|
318
|
-
* FR → 0002 (France SIRENE)
|
|
186
|
+
* Peppol/ISO 6523 ICD scheme for a legal registration number
|
|
187
|
+
* (`cac:PartyLegalEntity/cbc:CompanyID/@schemeID`), e.g. BE → `0208`
|
|
188
|
+
* (enterprise number), NL → `0106` (KvK), FR → `0002` (SIRENE). The table is
|
|
189
|
+
* `@financica/peppol`'s country profiles.
|
|
319
190
|
*
|
|
320
191
|
* Falls back to inspecting the number's country prefix (e.g. `BE0793904121`).
|
|
321
|
-
* Returns `
|
|
192
|
+
* Returns `undefined` when the scheme can't be determined, in which case the
|
|
322
193
|
* CompanyID is emitted without a `schemeID` attribute.
|
|
323
194
|
*/
|
|
324
195
|
declare const resolveCompanyIdScheme: (params: {
|
|
325
196
|
countryCode: string | null;
|
|
326
197
|
companyNumber: string | null;
|
|
327
|
-
}) => string |
|
|
198
|
+
}) => string | undefined;
|
|
328
199
|
/**
|
|
329
200
|
* Build the `cac:PartyLegalEntity/cbc:CompanyID` value for a party, with the
|
|
330
|
-
* country-appropriate ICD scheme when known. Returns `
|
|
201
|
+
* country-appropriate ICD scheme when known. Returns `undefined` when there is no
|
|
331
202
|
* company number.
|
|
332
203
|
*/
|
|
333
204
|
declare const buildCompanyId: (params: {
|
|
334
205
|
countryCode: string | null;
|
|
335
206
|
companyNumber: string | null;
|
|
336
|
-
}) => UblCompanyId |
|
|
207
|
+
}) => UblCompanyId | undefined;
|
|
337
208
|
/**
|
|
338
209
|
* Resolve the Peppol participant identifier for a VAT number, deriving the EAS
|
|
339
210
|
* scheme from the number's own country prefix (falling back to `countryCode`).
|
|
340
211
|
*
|
|
341
212
|
* `BE0206582284` → `{ scheme: "9925", value: "BE0206582284" }`
|
|
342
213
|
*
|
|
214
|
+
* The scheme comes from `@financica/peppol`'s country resolution, so countries
|
|
215
|
+
* that route on their registry number alone (Norway, Denmark) yield `undefined`
|
|
216
|
+
* here — their VAT number is not a Peppol participant identifier.
|
|
217
|
+
*
|
|
343
218
|
* The value keeps its country prefix, matching how participants register (the
|
|
344
|
-
* Peppol directory lists this party as `9925:be0206582284`). Returns `
|
|
219
|
+
* Peppol directory lists this party as `9925:be0206582284`). Returns `undefined`
|
|
345
220
|
* when the country has no VAT EAS scheme or the input is empty.
|
|
346
221
|
*/
|
|
347
222
|
declare const resolveVatEndpoint: (params: {
|
|
348
223
|
vatNumber: string | null | undefined;
|
|
349
|
-
countryCode?: string | null;
|
|
350
|
-
}) => UblEndpoint |
|
|
224
|
+
countryCode?: string | null | undefined;
|
|
225
|
+
}) => UblEndpoint | undefined;
|
|
351
226
|
/**
|
|
352
227
|
* Parse a Peppol participant identifier into a {@link UblEndpoint}.
|
|
353
228
|
*
|
|
354
229
|
* Accepts the canonical `scheme:value` form (e.g. `0208:0800279001`). Returns
|
|
355
|
-
* `
|
|
230
|
+
* `undefined` for values without an explicit scheme, since `cbc:EndpointID` requires
|
|
356
231
|
* a `schemeID` and guessing one would mis-route the document.
|
|
357
232
|
*/
|
|
358
|
-
declare const parsePeppolEndpoint: (peppolId: string | null | undefined) => UblEndpoint |
|
|
233
|
+
declare const parsePeppolEndpoint: (peppolId: string | null | undefined) => UblEndpoint | undefined;
|
|
359
234
|
interface CustomerTaxIdentifiers {
|
|
360
235
|
peppolID: string | null;
|
|
361
236
|
glnNumber: string | null;
|
|
362
237
|
taxNumber: string | null;
|
|
363
238
|
vatNumber: string | null;
|
|
364
239
|
}
|
|
240
|
+
/**
|
|
241
|
+
* One customer tax identifier as stored by Stripe (`customer_tax_ids[]`) or an
|
|
242
|
+
* equivalent `{type, value}` pair. `type` is a Stripe tax-ID type such as
|
|
243
|
+
* `eu_vat`, or a custom type such as `peppol_id`; blank entries are skipped.
|
|
244
|
+
*/
|
|
245
|
+
interface CustomerTaxIdInput {
|
|
246
|
+
type: string | null | undefined;
|
|
247
|
+
value: string | null | undefined;
|
|
248
|
+
}
|
|
365
249
|
/**
|
|
366
250
|
* Pick the first usable Peppol identifier, GLN, VAT number, and tax number
|
|
367
251
|
* from a Stripe-style `customer_tax_ids` array (`[{type, value}, …]`).
|
|
@@ -369,7 +253,7 @@ interface CustomerTaxIdentifiers {
|
|
|
369
253
|
* Stripe stores VAT numbers under types like `eu_vat`, `gb_vat`, etc.
|
|
370
254
|
* Peppol IDs are typically stored as a custom `peppol_id` type.
|
|
371
255
|
*/
|
|
372
|
-
declare const extractCustomerTaxIdentifiers: (taxIds:
|
|
256
|
+
declare const extractCustomerTaxIdentifiers: (taxIds: readonly CustomerTaxIdInput[] | null | undefined) => CustomerTaxIdentifiers;
|
|
373
257
|
/**
|
|
374
258
|
* Build the fully-qualified Peppol participant identifiers (`scheme:value`) a
|
|
375
259
|
* receiver lookup will accept, in priority order, de-duplicated.
|
|
@@ -389,40 +273,41 @@ declare const extractCustomerTaxIdentifiers: (taxIds: unknown) => CustomerTaxIde
|
|
|
389
273
|
* `countryCode` (the customer's country, when known) disambiguates schemes for
|
|
390
274
|
* identifiers that don't carry a country prefix (GLN, plain tax numbers).
|
|
391
275
|
*/
|
|
392
|
-
declare const listPeppolReceiverIdentifierCandidates: (customer:
|
|
393
|
-
peppolID?: string | null;
|
|
394
|
-
glnNumber?: string | null;
|
|
395
|
-
taxNumber?: string | null;
|
|
396
|
-
vatNumber?: string | null;
|
|
397
|
-
}, countryCode?: string | null) => string[];
|
|
276
|
+
declare const listPeppolReceiverIdentifierCandidates: (customer: Partial<CustomerTaxIdentifiers>, countryCode?: string | null) => string[];
|
|
398
277
|
//#endregion
|
|
399
278
|
//#region src/build/numeric.d.ts
|
|
400
279
|
/** Round a number to 2 decimal places (cents). */
|
|
401
280
|
declare const roundCurrency: (value: number) => number;
|
|
402
281
|
/** Convert an integer cent amount into a 2-decimal currency value. */
|
|
403
282
|
declare const centsToDecimal: (cents: number) => number;
|
|
404
|
-
/** The `cac:Price` pair for a line:
|
|
283
|
+
/** The `cac:Price` pair for a line: the per-unit price and the optional BT-149. */
|
|
405
284
|
interface UnitPrice {
|
|
406
|
-
/** `
|
|
407
|
-
|
|
408
|
-
/**
|
|
409
|
-
|
|
285
|
+
/** Net price of one unit (`UblLine.unitPrice`). */
|
|
286
|
+
unitPrice: number;
|
|
287
|
+
/**
|
|
288
|
+
* `cbc:BaseQuantity` (BT-149) — set when the per-unit price is not exact in
|
|
289
|
+
* cents; the serializer then emits `PriceAmount = unitPrice × baseQuantity`
|
|
290
|
+
* (the line net). Omitted = 1.
|
|
291
|
+
*/
|
|
292
|
+
baseQuantity?: number | undefined;
|
|
410
293
|
}
|
|
411
294
|
/**
|
|
412
295
|
* Derive the `cac:Price` for a line whose net total is authoritative.
|
|
413
296
|
*
|
|
414
297
|
* Peppol rule PEPPOL-EN16931-R120 checks
|
|
415
|
-
* `quantity × (
|
|
298
|
+
* `quantity × (PriceAmount ÷ BaseQuantity)` against the line net amount within
|
|
416
299
|
* a 0.02 tolerance. Naively rounding `net ÷ quantity` to cents breaks that
|
|
417
300
|
* whenever the division doesn't land on a cent: 940.00 over 14 units gives
|
|
418
301
|
* 67.142857…, which rounds to 67.14, and 14 × 67.14 = 939.96 — off by 0.04 and
|
|
419
302
|
* rejected as a fatal validation error.
|
|
420
303
|
*
|
|
421
304
|
* So the cent-rounded unit price is only used when it reproduces the net
|
|
422
|
-
* exactly. Otherwise the line is priced as a whole via BT-149
|
|
423
|
-
* the net
|
|
424
|
-
*
|
|
425
|
-
*
|
|
305
|
+
* exactly. Otherwise the line is priced as a whole via BT-149: `unitPrice` is
|
|
306
|
+
* the exact (unrounded) `net ÷ quantity` and `baseQuantity` = the quantity, so
|
|
307
|
+
* the serializer writes `PriceAmount` = the net and `BaseQuantity` = the
|
|
308
|
+
* quantity, which is exact at any magnitude instead of merely within tolerance
|
|
309
|
+
* — the residual of a rounded unit price grows with quantity and would
|
|
310
|
+
* eventually breach 0.02 at any fixed precision.
|
|
426
311
|
*/
|
|
427
312
|
declare const deriveUnitPrice: (netTotal: number, quantity: number) => UnitPrice;
|
|
428
313
|
//#endregion
|
|
@@ -460,6 +345,13 @@ declare const taxCategoryFromReasonOrRate: (params: {
|
|
|
460
345
|
* otherwise the rate decides standard (`S`) vs zero-rated (`Z`).
|
|
461
346
|
*/
|
|
462
347
|
declare const resolveTaxCategoryFromTaxAmounts: (taxAmounts: TaxAmountInfo[], rate: number) => UblTaxCategory;
|
|
348
|
+
/**
|
|
349
|
+
* When the supplier does not charge VAT, coerce every line to a non-charging
|
|
350
|
+
* exempt category (`E`, 0%) with the appropriate BT-120 reason, so the document
|
|
351
|
+
* reports no VAT regardless of what the upstream line tax data implied. Lines
|
|
352
|
+
* are returned untouched for a `subject` supplier.
|
|
353
|
+
*/
|
|
354
|
+
declare const coerceLinesForSupplierVatStatus: (lines: UblLine[], vatStatus: SupplierVatStatus, supplierCountryCode?: string | null) => UblLine[];
|
|
463
355
|
//#endregion
|
|
464
356
|
//#region src/build/tax-totals.d.ts
|
|
465
357
|
/**
|
|
@@ -502,6 +394,9 @@ interface BuildTaxTotalsOptions {
|
|
|
502
394
|
* invariant holds by construction. The result is *not* clamped: a prepayment
|
|
503
395
|
* exceeding the total yields a negative payable amount, surfacing the upstream
|
|
504
396
|
* overpayment rather than hiding it.
|
|
397
|
+
*
|
|
398
|
+
* @throws {UblBuildError} for a line without a `taxCategory` — there is no
|
|
399
|
+
* VAT breakdown to put it in.
|
|
505
400
|
*/
|
|
506
401
|
declare const buildTaxTotals: (lines: UblLine[], options?: BuildTaxTotalsOptions) => BuildTaxTotalsResult;
|
|
507
402
|
//#endregion
|
|
@@ -536,5 +431,11 @@ declare const el: (name: string, attrs?: XmlAttrs | null, content?: string | num
|
|
|
536
431
|
/** Serialize a root element into a UTF-8 XML document string. */
|
|
537
432
|
declare const serializeDocument: (root: XmlElement) => string;
|
|
538
433
|
//#endregion
|
|
539
|
-
|
|
434
|
+
//#region src/build/index.d.ts
|
|
435
|
+
/** @deprecated The build and parse models are one; use {@link UblInvoice}. */
|
|
436
|
+
type UblDocument = UblInvoice;
|
|
437
|
+
/** @deprecated Use {@link UblInvoicePeriod}. */
|
|
438
|
+
type UblPeriod = UblInvoicePeriod;
|
|
439
|
+
//#endregion
|
|
440
|
+
export { type AddressInput, type BuildTaxTotalsOptions, type BuildTaxTotalsResult, COUNTRY_CODE_LIST_ID, CREDIT_NOTE_TYPE_CODE, type CustomerTaxIdInput, type CustomerTaxIdentifiers, DEFAULT_UNIT_CODE, EXEMPT_TAXABILITY_REASONS, INVOICE_TYPE_CODE, NS_CAC, NS_CBC, NS_CREDIT_NOTE, NS_INVOICE, type SupplierVatStatus, type TaxAmountInfo, UBL_CUSTOMIZATION_ID, UBL_PROFILE_ID, type UblAddress, type UblAttachment, type UblBillingReference, UblBuildError, type UblCompanyId, type UblCustomer, UblDocument, type UblEndpoint, type UblInvoice, type UblInvoicePeriod, type UblLine, type UblMonetaryTotal, type UblParty, UblPeriod, type UblSupplier, type UblTaxCategory, type UblTaxSubtotal, type UblTaxTotal, type UnitPrice, VAT_TAX_SCHEME_ID, type XmlAttrs, type XmlElement, buildCompanyId, buildCustomerParty, buildPdfAttachment, buildSupplierParty, buildTaxTotals, centsToDecimal, coerceLinesForSupplierVatStatus, deriveUnitPrice, el, extractCustomerTaxIdentifiers, listPeppolReceiverIdentifierCandidates, normalizeAddress, normalizeCompanyNumberForCountry, parsePeppolEndpoint, reconcileLinesToExclTotal, resolveCompanyIdScheme, resolveTaxCategoryFromTaxAmounts, resolveVatEndpoint, roundCurrency, sanitizeUblDocumentForAudit, serializeDocument, serializeUblDocument, serializeUblInvoice, taxCategoryFromReasonOrRate };
|
|
540
441
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/build/ubl/constants.ts","../../src/build/ubl/
|
|
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"}
|