@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
|
@@ -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",
|
package/src/build/address.ts
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
import type { UblAddress } from "
|
|
2
|
-
import { normalizeString } from "./utils";
|
|
1
|
+
import type { UblAddress } from "../types";
|
|
2
|
+
import { compact, normalizeString } from "./utils";
|
|
3
3
|
|
|
4
|
-
const normalizeCountryCode = (value: string | null | undefined): string |
|
|
4
|
+
const normalizeCountryCode = (value: string | null | undefined): string | undefined => {
|
|
5
5
|
const trimmed = normalizeString(value);
|
|
6
|
-
if (!trimmed) return
|
|
7
|
-
return trimmed.length >= 2 ? trimmed.toUpperCase().slice(0, 2) :
|
|
6
|
+
if (!trimmed) return undefined;
|
|
7
|
+
return trimmed.length >= 2 ? trimmed.toUpperCase().slice(0, 2) : undefined;
|
|
8
8
|
};
|
|
9
9
|
|
|
10
10
|
/**
|
|
@@ -30,7 +30,7 @@ export interface AddressInput {
|
|
|
30
30
|
|
|
31
31
|
/**
|
|
32
32
|
* Normalize a free-form address (Stripe shape, custom shape, or an internal
|
|
33
|
-
* shape) into a {@link UblAddress}.
|
|
33
|
+
* shape) into a {@link UblAddress}. An absent part is an absent key.
|
|
34
34
|
*
|
|
35
35
|
* Accepts both `line1`/`postal_code`/`country` (Stripe) and `street`/`zip_code`
|
|
36
36
|
* (legacy/internal) keys. Falls back to `fallbackCountryCode` when the address
|
|
@@ -47,12 +47,11 @@ export const normalizeAddress = (
|
|
|
47
47
|
normalizeCountryCode(normalizeString(record.country)) ??
|
|
48
48
|
normalizeCountryCode(normalizeString(record.country_code)) ??
|
|
49
49
|
normalizeCountryCode(fallbackCountryCode);
|
|
50
|
-
return {
|
|
50
|
+
return compact({
|
|
51
51
|
street:
|
|
52
52
|
normalizeString(record.line1) ??
|
|
53
53
|
normalizeString(record.street) ??
|
|
54
|
-
fallbackLine
|
|
55
|
-
null,
|
|
54
|
+
normalizeString(fallbackLine),
|
|
56
55
|
additionalStreet: normalizeString(record.line2),
|
|
57
56
|
city: normalizeString(record.city),
|
|
58
57
|
postalZone:
|
|
@@ -60,5 +59,5 @@ export const normalizeAddress = (
|
|
|
60
59
|
countrySubentity:
|
|
61
60
|
normalizeString(record.state) ?? normalizeString(record.country_subentity),
|
|
62
61
|
countryCode,
|
|
63
|
-
};
|
|
62
|
+
});
|
|
64
63
|
};
|
package/src/build/attachment.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { UblAttachment,
|
|
1
|
+
import type { UblAttachment, UblInvoice } from "../types";
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
4
|
* Build a UBL embedded-document attachment (BG-24) from raw bytes — e.g. the
|
|
@@ -14,20 +14,24 @@ export const buildPdfAttachment = (params: {
|
|
|
14
14
|
id: params.id ?? params.filename,
|
|
15
15
|
filename: params.filename,
|
|
16
16
|
mimeCode: "application/pdf",
|
|
17
|
-
|
|
17
|
+
base64Content: Buffer.from(params.bytes).toString("base64"),
|
|
18
18
|
});
|
|
19
19
|
|
|
20
20
|
/**
|
|
21
21
|
* Replace each attachment's base64 payload with `[omitted]` plus a length, so a
|
|
22
|
-
* {@link
|
|
22
|
+
* {@link UblInvoice} is safe to log or persist for audit.
|
|
23
23
|
*/
|
|
24
|
-
export const sanitizeUblDocumentForAudit = (doc:
|
|
25
|
-
if (doc.attachments
|
|
24
|
+
export const sanitizeUblDocumentForAudit = (doc: UblInvoice): UblInvoice => {
|
|
25
|
+
if (!doc.attachments?.length) return doc;
|
|
26
26
|
return {
|
|
27
27
|
...doc,
|
|
28
|
-
attachments: doc.attachments.map((attachment) =>
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
28
|
+
attachments: doc.attachments.map((attachment) =>
|
|
29
|
+
attachment.base64Content === undefined
|
|
30
|
+
? attachment
|
|
31
|
+
: {
|
|
32
|
+
...attachment,
|
|
33
|
+
base64Content: `[omitted ${attachment.base64Content.length} chars]`,
|
|
34
|
+
},
|
|
35
|
+
),
|
|
32
36
|
};
|
|
33
37
|
};
|
package/src/build/identifiers.ts
CHANGED
|
@@ -3,8 +3,8 @@ import {
|
|
|
3
3
|
countryFromVatNumber,
|
|
4
4
|
normalizeParticipantValue,
|
|
5
5
|
} from "@financica/peppol/identifiers";
|
|
6
|
-
import type { UblCompanyId, UblEndpoint } from "
|
|
7
|
-
import { normalizeString } from "./utils";
|
|
6
|
+
import type { UblCompanyId, UblEndpoint } from "../types";
|
|
7
|
+
import { compact, normalizeString } from "./utils";
|
|
8
8
|
|
|
9
9
|
const normalizeBelgianCompanyNumber = (value: string | null | undefined) => {
|
|
10
10
|
if (!value) return "";
|
|
@@ -33,19 +33,19 @@ export const normalizeCompanyNumberForCountry = (
|
|
|
33
33
|
* `@financica/peppol`'s country profiles.
|
|
34
34
|
*
|
|
35
35
|
* Falls back to inspecting the number's country prefix (e.g. `BE0793904121`).
|
|
36
|
-
* Returns `
|
|
36
|
+
* Returns `undefined` when the scheme can't be determined, in which case the
|
|
37
37
|
* CompanyID is emitted without a `schemeID` attribute.
|
|
38
38
|
*/
|
|
39
39
|
export const resolveCompanyIdScheme = (params: {
|
|
40
40
|
countryCode: string | null;
|
|
41
41
|
companyNumber: string | null;
|
|
42
|
-
}): string |
|
|
42
|
+
}): string | undefined => {
|
|
43
43
|
const companyNumber = normalizeString(params.companyNumber);
|
|
44
|
-
if (!companyNumber) return
|
|
44
|
+
if (!companyNumber) return undefined;
|
|
45
45
|
|
|
46
|
-
const fromCountry =
|
|
47
|
-
params.countryCode
|
|
48
|
-
|
|
46
|
+
const fromCountry =
|
|
47
|
+
getPeppolIdentifierSchemes(params.countryCode)?.companyIdentifierScheme ??
|
|
48
|
+
undefined;
|
|
49
49
|
if (fromCountry) return fromCountry;
|
|
50
50
|
|
|
51
51
|
// Only sniffing the country prefix, e.g. `BE0793904121` → `BE`.
|
|
@@ -53,29 +53,29 @@ export const resolveCompanyIdScheme = (params: {
|
|
|
53
53
|
.replace(/[^A-Za-z]/g, "")
|
|
54
54
|
.toUpperCase()
|
|
55
55
|
.slice(0, 2);
|
|
56
|
-
return getPeppolIdentifierSchemes(prefix)?.companyIdentifierScheme ??
|
|
56
|
+
return getPeppolIdentifierSchemes(prefix)?.companyIdentifierScheme ?? undefined;
|
|
57
57
|
};
|
|
58
58
|
|
|
59
59
|
/**
|
|
60
60
|
* Build the `cac:PartyLegalEntity/cbc:CompanyID` value for a party, with the
|
|
61
|
-
* country-appropriate ICD scheme when known. Returns `
|
|
61
|
+
* country-appropriate ICD scheme when known. Returns `undefined` when there is no
|
|
62
62
|
* company number.
|
|
63
63
|
*/
|
|
64
64
|
export const buildCompanyId = (params: {
|
|
65
65
|
countryCode: string | null;
|
|
66
66
|
companyNumber: string | null;
|
|
67
|
-
}): UblCompanyId |
|
|
67
|
+
}): UblCompanyId | undefined => {
|
|
68
68
|
const normalized = normalizeString(
|
|
69
69
|
normalizeCompanyNumberForCountry(params.countryCode, params.companyNumber),
|
|
70
70
|
);
|
|
71
|
-
if (!normalized) return
|
|
72
|
-
return {
|
|
71
|
+
if (!normalized) return undefined;
|
|
72
|
+
return compact({
|
|
73
73
|
value: normalized,
|
|
74
74
|
scheme: resolveCompanyIdScheme({
|
|
75
75
|
countryCode: params.countryCode,
|
|
76
76
|
companyNumber: normalized,
|
|
77
77
|
}),
|
|
78
|
-
};
|
|
78
|
+
});
|
|
79
79
|
};
|
|
80
80
|
|
|
81
81
|
/**
|
|
@@ -85,30 +85,30 @@ export const buildCompanyId = (params: {
|
|
|
85
85
|
* `BE0206582284` → `{ scheme: "9925", value: "BE0206582284" }`
|
|
86
86
|
*
|
|
87
87
|
* The scheme comes from `@financica/peppol`'s country resolution, so countries
|
|
88
|
-
* that route on their registry number alone (Norway, Denmark) yield `
|
|
88
|
+
* that route on their registry number alone (Norway, Denmark) yield `undefined`
|
|
89
89
|
* here — their VAT number is not a Peppol participant identifier.
|
|
90
90
|
*
|
|
91
91
|
* The value keeps its country prefix, matching how participants register (the
|
|
92
|
-
* Peppol directory lists this party as `9925:be0206582284`). Returns `
|
|
92
|
+
* Peppol directory lists this party as `9925:be0206582284`). Returns `undefined`
|
|
93
93
|
* when the country has no VAT EAS scheme or the input is empty.
|
|
94
94
|
*/
|
|
95
95
|
export const resolveVatEndpoint = (params: {
|
|
96
96
|
vatNumber: string | null | undefined;
|
|
97
97
|
countryCode?: string | null | undefined;
|
|
98
|
-
}): UblEndpoint |
|
|
98
|
+
}): UblEndpoint | undefined => {
|
|
99
99
|
const value = normalizeString(params.vatNumber);
|
|
100
|
-
if (!value) return
|
|
100
|
+
if (!value) return undefined;
|
|
101
101
|
|
|
102
102
|
const fromPrefix = countryFromVatNumber(value);
|
|
103
103
|
const scheme =
|
|
104
104
|
getPeppolIdentifierSchemes(fromPrefix)?.vatIdentifierScheme ??
|
|
105
105
|
getPeppolIdentifierSchemes(params.countryCode)?.vatIdentifierScheme;
|
|
106
|
-
if (!scheme) return
|
|
106
|
+
if (!scheme) return undefined;
|
|
107
107
|
|
|
108
108
|
// Every scheme in the table is a VAT scheme, whose value carries no
|
|
109
109
|
// separator, so the printed dots/spaces are dropped.
|
|
110
110
|
const cleaned = normalizeParticipantValue(scheme, value).toUpperCase();
|
|
111
|
-
if (!cleaned) return
|
|
111
|
+
if (!cleaned) return undefined;
|
|
112
112
|
|
|
113
113
|
return { scheme, value: cleaned };
|
|
114
114
|
};
|
|
@@ -117,19 +117,19 @@ export const resolveVatEndpoint = (params: {
|
|
|
117
117
|
* Parse a Peppol participant identifier into a {@link UblEndpoint}.
|
|
118
118
|
*
|
|
119
119
|
* Accepts the canonical `scheme:value` form (e.g. `0208:0800279001`). Returns
|
|
120
|
-
* `
|
|
120
|
+
* `undefined` for values without an explicit scheme, since `cbc:EndpointID` requires
|
|
121
121
|
* a `schemeID` and guessing one would mis-route the document.
|
|
122
122
|
*/
|
|
123
123
|
export const parsePeppolEndpoint = (
|
|
124
124
|
peppolId: string | null | undefined,
|
|
125
|
-
): UblEndpoint |
|
|
125
|
+
): UblEndpoint | undefined => {
|
|
126
126
|
const normalized = normalizeString(peppolId);
|
|
127
|
-
if (!normalized) return
|
|
127
|
+
if (!normalized) return undefined;
|
|
128
128
|
const separatorIndex = normalized.indexOf(":");
|
|
129
|
-
if (separatorIndex <= 0) return
|
|
129
|
+
if (separatorIndex <= 0) return undefined;
|
|
130
130
|
const scheme = normalized.slice(0, separatorIndex).trim();
|
|
131
131
|
const value = normalized.slice(separatorIndex + 1).trim();
|
|
132
|
-
if (!scheme || !value) return
|
|
132
|
+
if (!scheme || !value) return undefined;
|
|
133
133
|
return { scheme, value };
|
|
134
134
|
};
|
|
135
135
|
|
|
@@ -150,8 +150,8 @@ export interface CustomerTaxIdInput {
|
|
|
150
150
|
value: string | null | undefined;
|
|
151
151
|
}
|
|
152
152
|
|
|
153
|
-
const normalizeIdentifierType = (value: string |
|
|
154
|
-
value?.toLowerCase().replace(/[^a-z0-9]+/g, "_")
|
|
153
|
+
const normalizeIdentifierType = (value: string | undefined) =>
|
|
154
|
+
value?.toLowerCase().replace(/[^a-z0-9]+/g, "_");
|
|
155
155
|
|
|
156
156
|
/**
|
|
157
157
|
* Pick the first usable Peppol identifier, GLN, VAT number, and tax number
|
|
@@ -217,7 +217,7 @@ export const listPeppolReceiverIdentifierCandidates = (
|
|
|
217
217
|
countryCode?: string | null,
|
|
218
218
|
): string[] => {
|
|
219
219
|
const candidates: string[] = [];
|
|
220
|
-
const add = (id: { scheme?: string |
|
|
220
|
+
const add = (id: { scheme?: string | undefined; value: string } | undefined) => {
|
|
221
221
|
if (id?.scheme && id.value) candidates.push(`${id.scheme}:${id.value}`);
|
|
222
222
|
};
|
|
223
223
|
|