@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.
@@ -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.15.1",
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.7.0 <1.0.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
+ };