@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
|
@@ -0,0 +1,389 @@
|
|
|
1
|
+
//#region src/errors.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* Thrown by the parse side of this package when input is broken: malformed
|
|
4
|
+
* XML, or a UBL document missing an element EN 16931 makes mandatory. A parser
|
|
5
|
+
* returns `null` instead when the input is well-formed but not the document
|
|
6
|
+
* type it parses.
|
|
7
|
+
*/
|
|
8
|
+
declare class UblParseError extends Error {
|
|
9
|
+
readonly cause?: unknown;
|
|
10
|
+
constructor(message: string, options?: {
|
|
11
|
+
cause?: unknown;
|
|
12
|
+
});
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Thrown by the build side when a model cannot be serialized: a field EN 16931
|
|
16
|
+
* / Peppol BIS Billing 3.0 makes mandatory on the wire is missing, or a build
|
|
17
|
+
* helper is handed input it cannot turn into one. The message names the BT /
|
|
18
|
+
* model field.
|
|
19
|
+
*/
|
|
20
|
+
declare class UblBuildError extends Error {
|
|
21
|
+
readonly cause?: unknown;
|
|
22
|
+
constructor(message: string, options?: {
|
|
23
|
+
cause?: unknown;
|
|
24
|
+
});
|
|
25
|
+
}
|
|
26
|
+
//#endregion
|
|
27
|
+
//#region src/types.d.ts
|
|
28
|
+
interface UblAddress {
|
|
29
|
+
/** `cbc:StreetName` (BT-35). */
|
|
30
|
+
street?: string | undefined;
|
|
31
|
+
/** `cbc:AdditionalStreetName` (BT-36). */
|
|
32
|
+
additionalStreet?: string | undefined;
|
|
33
|
+
/** `cbc:CityName` (BT-37). */
|
|
34
|
+
city?: string | undefined;
|
|
35
|
+
/** `cbc:PostalZone` (BT-38). */
|
|
36
|
+
postalZone?: string | undefined;
|
|
37
|
+
/** `cbc:CountrySubentity` (BT-39). */
|
|
38
|
+
countrySubentity?: string | undefined;
|
|
39
|
+
/** `cac:Country/cbc:IdentificationCode` (BT-40) — ISO 3166-1 alpha-2. */
|
|
40
|
+
countryCode?: string | undefined;
|
|
41
|
+
}
|
|
42
|
+
interface UblContact {
|
|
43
|
+
/** `cac:Contact/cbc:Name` (BT-41/BT-56). */
|
|
44
|
+
name?: string | undefined;
|
|
45
|
+
/** `cac:Contact/cbc:Telephone` (BT-42/BT-57). */
|
|
46
|
+
phone?: string | undefined;
|
|
47
|
+
/** `cac:Contact/cbc:ElectronicMail` (BT-43/BT-58). */
|
|
48
|
+
email?: string | undefined;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Peppol participant identifier (`cbc:EndpointID` + `@schemeID`), e.g. scheme
|
|
52
|
+
* `0208`, value `0800279001`. A document may state the value without a scheme;
|
|
53
|
+
* the serializer requires both.
|
|
54
|
+
*/
|
|
55
|
+
interface UblEndpoint {
|
|
56
|
+
value: string;
|
|
57
|
+
/** EAS scheme (`@schemeID`), e.g. `0208`. */
|
|
58
|
+
scheme?: string | undefined;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Legal registration identifier (`cac:PartyLegalEntity/cbc:CompanyID` +
|
|
62
|
+
* `@schemeID`), e.g. a Belgian enterprise number.
|
|
63
|
+
*/
|
|
64
|
+
interface UblCompanyId {
|
|
65
|
+
value: string;
|
|
66
|
+
/** ISO 6523 ICD scheme (`@schemeID`, e.g. `0208` for the Belgian CBE), when known. */
|
|
67
|
+
scheme?: string | undefined;
|
|
68
|
+
}
|
|
69
|
+
/** `cac:PartyIdentification/cbc:ID` (BT-29/BT-46) with its `@schemeID`. */
|
|
70
|
+
interface UblPartyIdentification {
|
|
71
|
+
id: string;
|
|
72
|
+
schemeId?: string | undefined;
|
|
73
|
+
}
|
|
74
|
+
interface UblParty {
|
|
75
|
+
/** `cac:PartyName/cbc:Name` (BT-28/BT-45). */
|
|
76
|
+
name?: string | undefined;
|
|
77
|
+
/** `cac:PartyLegalEntity/cbc:RegistrationName` (BT-27/BT-44). */
|
|
78
|
+
registrationName?: string | undefined;
|
|
79
|
+
/** `cac:PartyLegalEntity/cbc:CompanyLegalForm` (BT-33). */
|
|
80
|
+
companyLegalForm?: string | undefined;
|
|
81
|
+
/** `cac:PartyTaxScheme/cbc:CompanyID` (BT-31/BT-48) — the VAT identifier. */
|
|
82
|
+
vatId?: string | undefined;
|
|
83
|
+
/** `cac:PartyTaxScheme/cac:TaxScheme/cbc:ID`, normally `VAT`. */
|
|
84
|
+
taxSchemeId?: string | undefined;
|
|
85
|
+
/** `cac:PartyLegalEntity/cbc:CompanyID` (BT-30/BT-47). */
|
|
86
|
+
companyId?: UblCompanyId | undefined;
|
|
87
|
+
/** `cbc:EndpointID` (BT-34/BT-49) — the Peppol routing identifier. */
|
|
88
|
+
endpoint?: UblEndpoint | undefined;
|
|
89
|
+
partyIdentifications?: UblPartyIdentification[] | undefined;
|
|
90
|
+
address?: UblAddress | undefined;
|
|
91
|
+
contact?: UblContact | undefined;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* VAT category (`cac:ClassifiedTaxCategory` on a line, `cac:TaxCategory` in
|
|
95
|
+
* the VAT breakdown and on an allowance/charge). `id` is a UNCL5305 code:
|
|
96
|
+
* - `S` Standard rate
|
|
97
|
+
* - `Z` Zero-rated goods
|
|
98
|
+
* - `E` Exempt from VAT
|
|
99
|
+
* - `AE` VAT reverse charge
|
|
100
|
+
* - `O` Services outside scope of tax
|
|
101
|
+
* - `K` Intra-community supply
|
|
102
|
+
* - `G` Export outside the EU
|
|
103
|
+
*/
|
|
104
|
+
interface UblTaxCategory {
|
|
105
|
+
/** `cbc:ID` (BT-151/BT-118/BT-95/BT-102). */
|
|
106
|
+
id?: string | undefined;
|
|
107
|
+
/** `cbc:Percent` (BT-152/BT-119/BT-96/BT-103); absent for `O` and when the document omits it. */
|
|
108
|
+
percent?: number | undefined;
|
|
109
|
+
/** `cac:TaxScheme/cbc:ID`, normally `VAT`. */
|
|
110
|
+
schemeId?: string | undefined;
|
|
111
|
+
/** `cbc:TaxExemptionReason` (BT-120). Required by EN 16931 for non-charging categories. */
|
|
112
|
+
exemptionReason?: string | undefined;
|
|
113
|
+
/** `cbc:TaxExemptionReasonCode` (BT-121). */
|
|
114
|
+
exemptionReasonCode?: string | undefined;
|
|
115
|
+
}
|
|
116
|
+
interface UblItemProperty {
|
|
117
|
+
/** `cac:AdditionalItemProperty/cbc:Name` (BT-160). */
|
|
118
|
+
name: string;
|
|
119
|
+
/** `cac:AdditionalItemProperty/cbc:Value` (BT-161). */
|
|
120
|
+
value?: string | undefined;
|
|
121
|
+
}
|
|
122
|
+
interface UblLine {
|
|
123
|
+
/** `cbc:ID` (BT-126) — line identifier. */
|
|
124
|
+
id: string;
|
|
125
|
+
/** `cac:Item/cbc:Description` (BT-154). */
|
|
126
|
+
description?: string | undefined;
|
|
127
|
+
/** `cbc:InvoicedQuantity` / `cbc:CreditedQuantity` (BT-129). */
|
|
128
|
+
quantity?: number | undefined;
|
|
129
|
+
/** UN/ECE Rec 20 unit code (BT-130). */
|
|
130
|
+
unitCode?: string | undefined;
|
|
131
|
+
/**
|
|
132
|
+
* Net price of one unit: `cac:Price/cbc:PriceAmount` (BT-146) divided by
|
|
133
|
+
* `cbc:BaseQuantity` (BT-149, default 1).
|
|
134
|
+
*/
|
|
135
|
+
unitPrice?: number | undefined;
|
|
136
|
+
/** `cbc:LineExtensionAmount` (BT-131) — net of VAT, after line discounts. */
|
|
137
|
+
lineExtensionAmount?: number | undefined;
|
|
138
|
+
/**
|
|
139
|
+
* `cac:Price/cbc:BaseQuantity` (BT-149) — the number of units BT-146
|
|
140
|
+
* covers. Omitted means 1. Set it when the net doesn't divide evenly into
|
|
141
|
+
* cents, so `quantity × unitPrice` reproduces the line net exactly
|
|
142
|
+
* (PEPPOL-EN16931-R120); see `deriveUnitPrice`. The serializer emits
|
|
143
|
+
* `PriceAmount = unitPrice × baseQuantity`.
|
|
144
|
+
*/
|
|
145
|
+
baseQuantity?: number | undefined;
|
|
146
|
+
/** `cac:Item/cac:ClassifiedTaxCategory` (BT-151/BT-152). */
|
|
147
|
+
taxCategory?: UblTaxCategory | undefined;
|
|
148
|
+
/** Line VAT amount: `cac:TaxTotal/cbc:TaxAmount` when stated, else derived from the rate. */
|
|
149
|
+
taxAmount?: number | undefined;
|
|
150
|
+
/** Line-level `cac:TaxTotal/cac:TaxSubtotal` (not used by BIS Billing, seen in the wild). */
|
|
151
|
+
taxSubtotals?: UblTaxSubtotal[] | undefined;
|
|
152
|
+
allowanceCharges?: UblAllowanceCharge[] | undefined;
|
|
153
|
+
/** Sum of line-level allowances (absolute). */
|
|
154
|
+
discountAmount?: number | undefined;
|
|
155
|
+
/** Sum of line-level charges (absolute). */
|
|
156
|
+
chargeAmount?: number | undefined;
|
|
157
|
+
/** `cac:Item/cbc:Name` (BT-153). */
|
|
158
|
+
itemName?: string | undefined;
|
|
159
|
+
/** `cac:Item/cac:SellersItemIdentification/cbc:ID` (BT-155). */
|
|
160
|
+
sellersItemId?: string | undefined;
|
|
161
|
+
/** `cac:Item/cac:BuyersItemIdentification/cbc:ID` (BT-156). */
|
|
162
|
+
buyersItemId?: string | undefined;
|
|
163
|
+
additionalItemProperties?: UblItemProperty[] | undefined;
|
|
164
|
+
/** `cac:InvoicePeriod` (BT-134/BT-135) — the line's own service period. */
|
|
165
|
+
invoicePeriod?: UblInvoicePeriod | undefined;
|
|
166
|
+
}
|
|
167
|
+
interface UblAllowanceCharge {
|
|
168
|
+
/** `cbc:ChargeIndicator` — `true` for a charge, `false` for an allowance. */
|
|
169
|
+
chargeIndicator: boolean;
|
|
170
|
+
/** `cbc:Amount` (BT-92/BT-99). */
|
|
171
|
+
amount?: number | undefined;
|
|
172
|
+
/** `cbc:BaseAmount` (BT-93/BT-100). */
|
|
173
|
+
baseAmount?: number | undefined;
|
|
174
|
+
/** `cbc:MultiplierFactorNumeric` (BT-94/BT-101). */
|
|
175
|
+
multiplierFactorNumeric?: number | undefined;
|
|
176
|
+
/** `cbc:AllowanceChargeReason` (BT-97/BT-104). */
|
|
177
|
+
reason?: string | undefined;
|
|
178
|
+
/** `cbc:AllowanceChargeReasonCode` (BT-98/BT-105). */
|
|
179
|
+
reasonCode?: string | undefined;
|
|
180
|
+
/** `cac:TaxCategory` (BT-95/BT-96, BT-102/BT-103). */
|
|
181
|
+
taxCategory?: UblTaxCategory | undefined;
|
|
182
|
+
}
|
|
183
|
+
interface UblTaxSubtotal {
|
|
184
|
+
/** `cbc:TaxableAmount` (BT-116). */
|
|
185
|
+
taxableAmount?: number | undefined;
|
|
186
|
+
/** `cbc:TaxAmount` (BT-117). */
|
|
187
|
+
taxAmount?: number | undefined;
|
|
188
|
+
/** `cac:TaxCategory` (BT-118/BT-119/BT-120/BT-121). */
|
|
189
|
+
category?: UblTaxCategory | undefined;
|
|
190
|
+
}
|
|
191
|
+
interface UblTaxTotal {
|
|
192
|
+
/** `cac:TaxTotal/cbc:TaxAmount` (BT-110). Read as stated; never summed from the subtotals. */
|
|
193
|
+
taxAmount?: number | undefined;
|
|
194
|
+
/** `cac:TaxSubtotal` (BG-23) — the VAT breakdown. */
|
|
195
|
+
subtotals: UblTaxSubtotal[];
|
|
196
|
+
}
|
|
197
|
+
interface UblMonetaryTotal {
|
|
198
|
+
/** BT-106 — sum of line net amounts. */
|
|
199
|
+
lineExtensionAmount?: number | undefined;
|
|
200
|
+
/** BT-109 — total without VAT. */
|
|
201
|
+
taxExclusiveAmount?: number | undefined;
|
|
202
|
+
/** BT-112 — total with VAT. */
|
|
203
|
+
taxInclusiveAmount?: number | undefined;
|
|
204
|
+
/** BT-107 — sum of document-level allowances. */
|
|
205
|
+
allowanceTotalAmount?: number | undefined;
|
|
206
|
+
/** BT-108 — sum of document-level charges. */
|
|
207
|
+
chargeTotalAmount?: number | undefined;
|
|
208
|
+
/**
|
|
209
|
+
* BT-113 — sum of amounts paid in advance. **Gross (VAT-inclusive)**, since
|
|
210
|
+
* BR-CO-16 subtracts it directly from BT-112.
|
|
211
|
+
*/
|
|
212
|
+
prepaidAmount?: number | undefined;
|
|
213
|
+
/** BT-114 — rounding applied to the payable amount. */
|
|
214
|
+
payableRoundingAmount?: number | undefined;
|
|
215
|
+
/**
|
|
216
|
+
* BT-115 — amount due for payment, i.e. the *outstanding* amount.
|
|
217
|
+
* BR-CO-16: `BT-115 = BT-112 − BT-113 + BT-114`.
|
|
218
|
+
*/
|
|
219
|
+
payableAmount?: number | undefined;
|
|
220
|
+
}
|
|
221
|
+
interface UblPaymentMeans {
|
|
222
|
+
/** `cbc:PaymentMeansCode` (BT-81). */
|
|
223
|
+
code?: string | undefined;
|
|
224
|
+
/** `cbc:PaymentMeansCode/@name` (BT-82). */
|
|
225
|
+
codeName?: string | undefined;
|
|
226
|
+
/** `cbc:PaymentID` (BT-83). */
|
|
227
|
+
paymentId?: string | undefined;
|
|
228
|
+
/** `cac:PayeeFinancialAccount/cbc:ID` (BT-84). */
|
|
229
|
+
iban?: string | undefined;
|
|
230
|
+
/** `cac:FinancialInstitutionBranch/cbc:ID` (BT-86). */
|
|
231
|
+
bic?: string | undefined;
|
|
232
|
+
/** `cac:PayeeFinancialAccount/cbc:Name` (BT-85). */
|
|
233
|
+
accountName?: string | undefined;
|
|
234
|
+
/** `cac:PaymentMandate/cbc:ID` (BT-89). */
|
|
235
|
+
mandateId?: string | undefined;
|
|
236
|
+
}
|
|
237
|
+
/**
|
|
238
|
+
* A service period: BT-73/BT-74 on the document, BT-134/BT-135 on a line.
|
|
239
|
+
* Either bound may stand alone — UBL allows a half-open period — but a period
|
|
240
|
+
* with neither is omitted entirely.
|
|
241
|
+
*/
|
|
242
|
+
interface UblInvoicePeriod {
|
|
243
|
+
/** `cbc:StartDate`, `YYYY-MM-DD`. */
|
|
244
|
+
startDate?: string | undefined;
|
|
245
|
+
/** `cbc:EndDate`, `YYYY-MM-DD`, inclusive. */
|
|
246
|
+
endDate?: string | undefined;
|
|
247
|
+
/** `cbc:DescriptionCode` (BT-8). */
|
|
248
|
+
descriptionCode?: string | undefined;
|
|
249
|
+
}
|
|
250
|
+
/** A supporting document (BG-24): embedded (`base64Content`) or external (`externalUri`). */
|
|
251
|
+
interface UblAttachment {
|
|
252
|
+
/** `cac:AdditionalDocumentReference/cbc:ID` (BT-122). */
|
|
253
|
+
id?: string | undefined;
|
|
254
|
+
/** `cbc:EmbeddedDocumentBinaryObject/@filename` (BT-125-2). */
|
|
255
|
+
filename?: string | undefined;
|
|
256
|
+
/** MIME type (BT-125-1), e.g. `application/pdf`. */
|
|
257
|
+
mimeCode?: string | undefined;
|
|
258
|
+
/** `cbc:DocumentDescription` (BT-123). */
|
|
259
|
+
description?: string | undefined;
|
|
260
|
+
/** Base64-encoded document bytes (BT-125). */
|
|
261
|
+
base64Content?: string | undefined;
|
|
262
|
+
/** `cac:ExternalReference/cbc:URI` (BT-124). */
|
|
263
|
+
externalUri?: string | undefined;
|
|
264
|
+
}
|
|
265
|
+
/** A text-only `cac:AdditionalDocumentReference` (no attachment). */
|
|
266
|
+
interface UblDocumentReference {
|
|
267
|
+
id?: string | undefined;
|
|
268
|
+
description?: string | undefined;
|
|
269
|
+
}
|
|
270
|
+
interface UblDelivery {
|
|
271
|
+
/** `cbc:ActualDeliveryDate` (BT-72). */
|
|
272
|
+
actualDeliveryDate?: string | undefined;
|
|
273
|
+
/** `cac:DeliveryLocation/cac:Address` (BG-15). */
|
|
274
|
+
address?: UblAddress | undefined;
|
|
275
|
+
}
|
|
276
|
+
/** `cac:BillingReference/cac:InvoiceDocumentReference` (BT-25/BT-26). */
|
|
277
|
+
interface UblBillingReference {
|
|
278
|
+
invoiceId?: string | undefined;
|
|
279
|
+
invoiceIssueDate?: string | undefined;
|
|
280
|
+
}
|
|
281
|
+
interface UblInvoice {
|
|
282
|
+
documentType: "Invoice" | "CreditNote";
|
|
283
|
+
/** `cbc:CustomizationID` (BT-24). The serializer defaults to Peppol BIS Billing 3.0. */
|
|
284
|
+
customizationId?: string | undefined;
|
|
285
|
+
/** `cbc:ProfileID` (BT-23). The serializer defaults to the Peppol billing process. */
|
|
286
|
+
profileId?: string | undefined;
|
|
287
|
+
/** Invoice / credit note number (BT-1). */
|
|
288
|
+
id: string;
|
|
289
|
+
/** `cbc:InvoiceTypeCode` / `cbc:CreditNoteTypeCode` (BT-3). The serializer defaults to 380/381. */
|
|
290
|
+
invoiceTypeCode?: string | undefined;
|
|
291
|
+
/** Issue date (BT-2), `YYYY-MM-DD`. */
|
|
292
|
+
issueDate: string;
|
|
293
|
+
/** Payment due date (BT-9). Invoices only. */
|
|
294
|
+
dueDate?: string | undefined;
|
|
295
|
+
/** `cbc:TaxPointDate` (BT-7). */
|
|
296
|
+
taxPointDate?: string | undefined;
|
|
297
|
+
/** Document currency (BT-5). */
|
|
298
|
+
currency: string;
|
|
299
|
+
/** Buyer reference (BT-10). */
|
|
300
|
+
buyerReference?: string | undefined;
|
|
301
|
+
/** `cac:OrderReference/cbc:ID` (BT-13). */
|
|
302
|
+
orderReference?: string | undefined;
|
|
303
|
+
/** `cac:OrderReference/cbc:SalesOrderID` (BT-14). */
|
|
304
|
+
salesOrderId?: string | undefined;
|
|
305
|
+
/** `cac:ContractDocumentReference/cbc:ID` (BT-12). */
|
|
306
|
+
contractReference?: string | undefined;
|
|
307
|
+
/** `cac:ProjectReference/cbc:ID` (BT-11). */
|
|
308
|
+
projectReference?: string | undefined;
|
|
309
|
+
/** For credit notes: the referenced original invoice (BT-25). */
|
|
310
|
+
billingReference?: UblBillingReference | undefined;
|
|
311
|
+
seller: UblParty;
|
|
312
|
+
buyer: UblParty;
|
|
313
|
+
delivery?: UblDelivery | undefined;
|
|
314
|
+
lines: UblLine[];
|
|
315
|
+
taxTotal: UblTaxTotal;
|
|
316
|
+
monetaryTotal: UblMonetaryTotal;
|
|
317
|
+
/** The first entry of `paymentMeansList`. */
|
|
318
|
+
paymentMeans?: UblPaymentMeans | undefined;
|
|
319
|
+
paymentMeansList?: UblPaymentMeans[] | undefined;
|
|
320
|
+
/** Invoicing period (BT-73/BT-74). */
|
|
321
|
+
invoicePeriod?: UblInvoicePeriod | undefined;
|
|
322
|
+
/** Free-text note (BT-22). */
|
|
323
|
+
note?: string | undefined;
|
|
324
|
+
/** Payment terms note (BT-20, `cac:PaymentTerms/cbc:Note`). */
|
|
325
|
+
paymentTermsNote?: string | undefined;
|
|
326
|
+
attachments?: UblAttachment[] | undefined;
|
|
327
|
+
documentReferences?: UblDocumentReference[] | undefined;
|
|
328
|
+
/** Document-level allowances and charges (BG-20/BG-21). */
|
|
329
|
+
allowanceCharges?: UblAllowanceCharge[] | undefined;
|
|
330
|
+
}
|
|
331
|
+
interface InvoiceExtractionDTO {
|
|
332
|
+
provider: string;
|
|
333
|
+
document_id: string;
|
|
334
|
+
invoice: {
|
|
335
|
+
invoice_number: string | null;
|
|
336
|
+
invoice_date: string | null;
|
|
337
|
+
due_date: string | null;
|
|
338
|
+
/** EN 16931 BT-73/BT-74: the period the document bills for. */
|
|
339
|
+
period_start: string | null;
|
|
340
|
+
period_end: string | null;
|
|
341
|
+
currency: string | null;
|
|
342
|
+
subtotal: number | null;
|
|
343
|
+
tax_total: number | null;
|
|
344
|
+
total: number | null;
|
|
345
|
+
amount_due: number | null;
|
|
346
|
+
amount_paid: number | null;
|
|
347
|
+
discount_total: number | null;
|
|
348
|
+
shipping_total: number | null;
|
|
349
|
+
/** EN 16931 BT-114, signed. Outside the VAT breakdown (BR-CO-16). */
|
|
350
|
+
rounding_total: number | null;
|
|
351
|
+
payment_terms: string | null;
|
|
352
|
+
po_number: string | null;
|
|
353
|
+
supplier: {
|
|
354
|
+
name: string | null;
|
|
355
|
+
address: string | null;
|
|
356
|
+
tax_id: string | null;
|
|
357
|
+
iban: string | null;
|
|
358
|
+
bic: string | null;
|
|
359
|
+
};
|
|
360
|
+
receiver: {
|
|
361
|
+
name: string | null;
|
|
362
|
+
address: string | null;
|
|
363
|
+
tax_id: string | null;
|
|
364
|
+
};
|
|
365
|
+
extra: Record<string, unknown>;
|
|
366
|
+
};
|
|
367
|
+
line_items: Array<{
|
|
368
|
+
description: string;
|
|
369
|
+
quantity: number | null;
|
|
370
|
+
unit: string | null;
|
|
371
|
+
unit_price: number | null;
|
|
372
|
+
amount: number | null;
|
|
373
|
+
tax_amount: number | null;
|
|
374
|
+
tax_rate: number | null;
|
|
375
|
+
product_code: string | null;
|
|
376
|
+
discount_amount: number | null;
|
|
377
|
+
/** EN 16931 BT-134/BT-135: the line's own service period. */
|
|
378
|
+
period_start: string | null;
|
|
379
|
+
period_end: string | null;
|
|
380
|
+
extra: Record<string, unknown>;
|
|
381
|
+
}>;
|
|
382
|
+
confidence: {
|
|
383
|
+
overall: number | null;
|
|
384
|
+
fields: Record<string, number>;
|
|
385
|
+
};
|
|
386
|
+
}
|
|
387
|
+
//#endregion
|
|
388
|
+
export { UblParseError as C, UblBuildError as S, UblPartyIdentification as _, UblBillingReference as a, UblTaxSubtotal as b, UblDelivery as c, UblInvoice as d, UblInvoicePeriod as f, UblParty as g, UblMonetaryTotal as h, UblAttachment as i, UblDocumentReference as l, UblLine as m, UblAddress as n, UblCompanyId as o, UblItemProperty as p, UblAllowanceCharge as r, UblContact as s, InvoiceExtractionDTO as t, UblEndpoint as u, UblPaymentMeans as v, UblTaxTotal as x, UblTaxCategory as y };
|
|
389
|
+
//# sourceMappingURL=types-DossV2at.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types-DossV2at.d.ts","names":[],"sources":["../src/errors.ts","../src/types.ts"],"mappings":";;;;;;;cAMa,sBAAsB;WAChB;EAElB,YAAY,iBAAiB;IAAY;;;;;;;;;cAa7B,sBAAsB;WAChB;EAElB,YAAY,iBAAiB;IAAY;;;;;UCRzB;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;UAGgB;;EAEhB;;EAEA;;EAEA;;;;;;;UAQgB;EAChB;;EAEA;;;;;;UAOgB;EAChB;;EAEA;;;UAIgB;EAChB;EACA;;UAGgB;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA,YAAY;;EAEZ,WAAW;EACX,uBAAuB;EACvB,UAAU;EACV,UAAU;;;;;;;;;;;;;UAcM;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;UAGgB;;EAEhB;;EAEA;;UAGgB;;EAEhB;;EAEA;;EAEA;;EAEA;;;;;EAKA;;EAEA;;;;;;;;EAQA;;EAEA,cAAc;;EAEd;;EAEA,eAAe;EACf,mBAAmB;;EAEnB;;EAEA;;EAEA;;EAEA;;EAEA;EACA,2BAA2B;;EAE3B,gBAAgB;;UAGA;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA,cAAc;;UAGE;;EAEhB;;EAEA;;EAEA,WAAW;;UAGK;;EAEhB;;EAEA,WAAW;;UAGK;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;;;;EAKA;;EAEA;;;;;EAKA;;UAGgB;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;UAQgB;;EAEhB;;EAEA;;EAEA;;;UAIgB;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;UAIgB;EAChB;EACA;;UAGgB;;EAEhB;;EAEA,UAAU;;;UAIM;EAChB;EACA;;UAGgB;EAChB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA,mBAAmB;EACnB,QAAQ;EACR,OAAO;EACP,WAAW;EACX,OAAO;EACP,UAAU;EACV,eAAe;;EAEf,eAAe;EACf,mBAAmB;;EAEnB,gBAAgB;;EAEhB;;EAEA;EACA,cAAc;EACd,qBAAqB;;EAErB,mBAAmB;;UAKH;EAChB;EACA;EACA;IACC;IACA;IACA;;IAEA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;;IAEA;IACA;IACA;IACA;MACC;MACA;MACA;MACA;MACA;;IAED;MACC;MACA;MACA;;IAED,OAAO;;EAER,YAAY;IACX;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;;IAEA;IACA;IACA,OAAO;;EAER;IACC;IACA,QAAQ"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@financica/ubl",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.17.0",
|
|
4
4
|
"description": "UBL (Universal Business Language) invoice toolkit for TypeScript: parse, build, and serialize Peppol BIS Billing 3.0 documents.",
|
|
5
5
|
"homepage": "https://github.com/financica/ts-libs/tree/main/packages/ubl#readme",
|
|
6
6
|
"bugs": "https://github.com/financica/ts-libs/issues",
|
|
@@ -11,9 +11,17 @@
|
|
|
11
11
|
"directory": "packages/ubl"
|
|
12
12
|
},
|
|
13
13
|
"files": [
|
|
14
|
-
"dist"
|
|
14
|
+
"dist",
|
|
15
|
+
"src",
|
|
16
|
+
"!src/**/*.test.ts",
|
|
17
|
+
"!src/**/*.test.tsx",
|
|
18
|
+
"!src/**/__tests__/**",
|
|
19
|
+
"CHANGELOG.md",
|
|
20
|
+
"LICENSE",
|
|
21
|
+
"README.md"
|
|
15
22
|
],
|
|
16
23
|
"type": "module",
|
|
24
|
+
"sideEffects": false,
|
|
17
25
|
"main": "./dist/index.js",
|
|
18
26
|
"types": "./dist/index.d.ts",
|
|
19
27
|
"exports": {
|
|
@@ -24,7 +32,8 @@
|
|
|
24
32
|
"./build": {
|
|
25
33
|
"types": "./dist/build/index.d.ts",
|
|
26
34
|
"import": "./dist/build/index.js"
|
|
27
|
-
}
|
|
35
|
+
},
|
|
36
|
+
"./package.json": "./package.json"
|
|
28
37
|
},
|
|
29
38
|
"publishConfig": {
|
|
30
39
|
"access": "public"
|
|
@@ -37,14 +46,14 @@
|
|
|
37
46
|
"lint:fix": "oxlint --fix",
|
|
38
47
|
"format": "oxfmt",
|
|
39
48
|
"format:check": "oxfmt --check",
|
|
40
|
-
"test": "vitest run",
|
|
41
|
-
"test:watch": "vitest",
|
|
42
|
-
"test:coverage": "vitest run --coverage",
|
|
49
|
+
"test": "vitest run --root ../.. --project @financica/ubl",
|
|
50
|
+
"test:watch": "vitest --root ../.. --project @financica/ubl",
|
|
51
|
+
"test:coverage": "vitest --root ../.. --project @financica/ubl run --coverage",
|
|
43
52
|
"ci": "bun run lint && bun run format:check && bun run build && bun run typecheck && bun run test",
|
|
44
53
|
"prepack": "bun run build"
|
|
45
54
|
},
|
|
46
55
|
"dependencies": {
|
|
47
|
-
"@financica/peppol": ">=0.
|
|
56
|
+
"@financica/peppol": ">=0.8.0 <1.0.0",
|
|
48
57
|
"@xmldom/xmldom": "^0.9.11"
|
|
49
58
|
},
|
|
50
59
|
"engines": {
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { UblParseError } from "./errors.js";
|
|
2
|
+
import { parseUblInvoice } from "./parser.js";
|
|
3
|
+
import type { UblAttachment } from "./types.js";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* An embedded attachment extracted from a UBL document's
|
|
7
|
+
* `AdditionalDocumentReference` entries, with its binary content still
|
|
8
|
+
* base64-encoded. `sizeBytes` is the decoded size.
|
|
9
|
+
*/
|
|
10
|
+
export interface UblEmbeddedAttachment {
|
|
11
|
+
id?: string | undefined;
|
|
12
|
+
filename: string;
|
|
13
|
+
mimeCode: string;
|
|
14
|
+
sizeBytes: number;
|
|
15
|
+
/** Zero-based position among the document's embedded attachments. */
|
|
16
|
+
lineOrder: number;
|
|
17
|
+
base64Content: string;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** Decoded byte length of a base64 string, accounting for `=` padding. */
|
|
21
|
+
export const base64DecodedSize = (base64: string): number => {
|
|
22
|
+
const sanitized = base64.replace(/\s+/g, "");
|
|
23
|
+
if (!sanitized) return 0;
|
|
24
|
+
const padding = sanitized.endsWith("==") ? 2 : sanitized.endsWith("=") ? 1 : 0;
|
|
25
|
+
return Math.floor((sanitized.length * 3) / 4) - padding;
|
|
26
|
+
};
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Extract the embedded attachments (typically the human-readable PDF) from a
|
|
30
|
+
* UBL invoice or credit note XML. Attachments referenced only by external URI
|
|
31
|
+
* (no `EmbeddedDocumentBinaryObject`) are skipped; use {@link parseUblInvoice}
|
|
32
|
+
* directly when those matter.
|
|
33
|
+
*
|
|
34
|
+
* @throws {UblParseError} when the XML is malformed or not a UBL invoice.
|
|
35
|
+
*/
|
|
36
|
+
export const extractUblEmbeddedAttachments = (xml: string): UblEmbeddedAttachment[] => {
|
|
37
|
+
const parsed = parseUblInvoice(xml);
|
|
38
|
+
if (!parsed) throw new UblParseError("Document is not a UBL Invoice or CreditNote");
|
|
39
|
+
if (!parsed.attachments || parsed.attachments.length === 0) return [];
|
|
40
|
+
|
|
41
|
+
return parsed.attachments
|
|
42
|
+
.map((attachment, index): UblEmbeddedAttachment | null => {
|
|
43
|
+
const base64Content = attachment.base64Content?.trim();
|
|
44
|
+
if (!base64Content) return null;
|
|
45
|
+
return {
|
|
46
|
+
id: attachment.id,
|
|
47
|
+
filename: attachment.filename ?? `attachment-${index + 1}`,
|
|
48
|
+
mimeCode: attachment.mimeCode ?? "application/octet-stream",
|
|
49
|
+
sizeBytes: base64DecodedSize(base64Content),
|
|
50
|
+
lineOrder: index,
|
|
51
|
+
base64Content,
|
|
52
|
+
};
|
|
53
|
+
})
|
|
54
|
+
.filter((entry): entry is UblEmbeddedAttachment => entry !== null);
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Whether an attachment looks like a PDF, by MIME type first and filename
|
|
59
|
+
* extension as a fallback.
|
|
60
|
+
*/
|
|
61
|
+
export const isPdfLikeAttachment = (
|
|
62
|
+
attachment: Pick<UblAttachment, "filename" | "mimeCode">,
|
|
63
|
+
): boolean => {
|
|
64
|
+
const mimeCode = attachment.mimeCode?.toLowerCase() ?? "";
|
|
65
|
+
if (mimeCode === "application/pdf" || mimeCode.endsWith("/pdf")) return true;
|
|
66
|
+
return attachment.filename?.toLowerCase().endsWith(".pdf") ?? false;
|
|
67
|
+
};
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import type { UblAddress } from "../types";
|
|
2
|
+
import { compact, normalizeString } from "./utils";
|
|
3
|
+
|
|
4
|
+
const normalizeCountryCode = (value: string | null | undefined): string | undefined => {
|
|
5
|
+
const trimmed = normalizeString(value);
|
|
6
|
+
if (!trimmed) return undefined;
|
|
7
|
+
return trimmed.length >= 2 ? trimmed.toUpperCase().slice(0, 2) : undefined;
|
|
8
|
+
};
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* A free-form postal address as accepted by {@link normalizeAddress}.
|
|
12
|
+
*
|
|
13
|
+
* Both the Stripe shape (`line1`, `postal_code`, `country`, `state`) and the
|
|
14
|
+
* legacy/internal shape (`street`, `zip_code`, `country_code`,
|
|
15
|
+
* `country_subentity`) are accepted; when both keys are present the Stripe
|
|
16
|
+
* one wins.
|
|
17
|
+
*/
|
|
18
|
+
export interface AddressInput {
|
|
19
|
+
line1?: string | null;
|
|
20
|
+
line2?: string | null;
|
|
21
|
+
street?: string | null;
|
|
22
|
+
city?: string | null;
|
|
23
|
+
postal_code?: string | null;
|
|
24
|
+
zip_code?: string | null;
|
|
25
|
+
state?: string | null;
|
|
26
|
+
country_subentity?: string | null;
|
|
27
|
+
country?: string | null;
|
|
28
|
+
country_code?: string | null;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Normalize a free-form address (Stripe shape, custom shape, or an internal
|
|
33
|
+
* shape) into a {@link UblAddress}. An absent part is an absent key.
|
|
34
|
+
*
|
|
35
|
+
* Accepts both `line1`/`postal_code`/`country` (Stripe) and `street`/`zip_code`
|
|
36
|
+
* (legacy/internal) keys. Falls back to `fallbackCountryCode` when the address
|
|
37
|
+
* has no country, but never silently substitutes a caller's country — pass
|
|
38
|
+
* `null` when "no country" is the right answer.
|
|
39
|
+
*/
|
|
40
|
+
export const normalizeAddress = (
|
|
41
|
+
address: AddressInput | null | undefined,
|
|
42
|
+
fallbackCountryCode: string | null,
|
|
43
|
+
fallbackLine?: string | null,
|
|
44
|
+
): UblAddress => {
|
|
45
|
+
const record: AddressInput = address ?? {};
|
|
46
|
+
const countryCode =
|
|
47
|
+
normalizeCountryCode(normalizeString(record.country)) ??
|
|
48
|
+
normalizeCountryCode(normalizeString(record.country_code)) ??
|
|
49
|
+
normalizeCountryCode(fallbackCountryCode);
|
|
50
|
+
return compact({
|
|
51
|
+
street:
|
|
52
|
+
normalizeString(record.line1) ??
|
|
53
|
+
normalizeString(record.street) ??
|
|
54
|
+
normalizeString(fallbackLine),
|
|
55
|
+
additionalStreet: normalizeString(record.line2),
|
|
56
|
+
city: normalizeString(record.city),
|
|
57
|
+
postalZone:
|
|
58
|
+
normalizeString(record.postal_code) ?? normalizeString(record.zip_code),
|
|
59
|
+
countrySubentity:
|
|
60
|
+
normalizeString(record.state) ?? normalizeString(record.country_subentity),
|
|
61
|
+
countryCode,
|
|
62
|
+
});
|
|
63
|
+
};
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import type { UblAttachment, UblInvoice } from "../types";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Build a UBL embedded-document attachment (BG-24) from raw bytes — e.g. the
|
|
5
|
+
* rendered PDF of the invoice. Emitted as a `cac:AdditionalDocumentReference`
|
|
6
|
+
* with an inline base64 `cbc:EmbeddedDocumentBinaryObject`.
|
|
7
|
+
*/
|
|
8
|
+
export const buildPdfAttachment = (params: {
|
|
9
|
+
filename: string;
|
|
10
|
+
bytes: Uint8Array;
|
|
11
|
+
/** Document reference ID (BT-122). Defaults to the filename. */
|
|
12
|
+
id?: string;
|
|
13
|
+
}): UblAttachment => ({
|
|
14
|
+
id: params.id ?? params.filename,
|
|
15
|
+
filename: params.filename,
|
|
16
|
+
mimeCode: "application/pdf",
|
|
17
|
+
base64Content: Buffer.from(params.bytes).toString("base64"),
|
|
18
|
+
});
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Replace each attachment's base64 payload with `[omitted]` plus a length, so a
|
|
22
|
+
* {@link UblInvoice} is safe to log or persist for audit.
|
|
23
|
+
*/
|
|
24
|
+
export const sanitizeUblDocumentForAudit = (doc: UblInvoice): UblInvoice => {
|
|
25
|
+
if (!doc.attachments?.length) return doc;
|
|
26
|
+
return {
|
|
27
|
+
...doc,
|
|
28
|
+
attachments: doc.attachments.map((attachment) =>
|
|
29
|
+
attachment.base64Content === undefined
|
|
30
|
+
? attachment
|
|
31
|
+
: {
|
|
32
|
+
...attachment,
|
|
33
|
+
base64Content: `[omitted ${attachment.base64Content.length} chars]`,
|
|
34
|
+
},
|
|
35
|
+
),
|
|
36
|
+
};
|
|
37
|
+
};
|