@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.
@@ -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.16.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",
@@ -1,10 +1,10 @@
1
- import type { UblAddress } from "./ubl/types";
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 | null => {
4
+ const normalizeCountryCode = (value: string | null | undefined): string | undefined => {
5
5
  const trimmed = normalizeString(value);
6
- if (!trimmed) return null;
7
- return trimmed.length >= 2 ? trimmed.toUpperCase().slice(0, 2) : null;
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
  };
@@ -1,4 +1,4 @@
1
- import type { UblAttachment, UblDocument } from "./ubl/types";
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
- base64: Buffer.from(params.bytes).toString("base64"),
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 UblDocument} is safe to log or persist for audit.
22
+ * {@link UblInvoice} is safe to log or persist for audit.
23
23
  */
24
- export const sanitizeUblDocumentForAudit = (doc: UblDocument): UblDocument => {
25
- if (doc.attachments.length === 0) return doc;
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
- ...attachment,
30
- base64: `[omitted ${attachment.base64.length} chars]`,
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
  };
@@ -3,8 +3,8 @@ import {
3
3
  countryFromVatNumber,
4
4
  normalizeParticipantValue,
5
5
  } from "@financica/peppol/identifiers";
6
- import type { UblCompanyId, UblEndpoint } from "./ubl/types";
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 `null` when the scheme can't be determined, in which case the
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 | null => {
42
+ }): string | undefined => {
43
43
  const companyNumber = normalizeString(params.companyNumber);
44
- if (!companyNumber) return null;
44
+ if (!companyNumber) return undefined;
45
45
 
46
- const fromCountry = getPeppolIdentifierSchemes(
47
- params.countryCode,
48
- )?.companyIdentifierScheme;
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 ?? null;
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 `null` when there is no
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 | null => {
67
+ }): UblCompanyId | undefined => {
68
68
  const normalized = normalizeString(
69
69
  normalizeCompanyNumberForCountry(params.countryCode, params.companyNumber),
70
70
  );
71
- if (!normalized) return null;
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 `null`
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 `null`
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 | null => {
98
+ }): UblEndpoint | undefined => {
99
99
  const value = normalizeString(params.vatNumber);
100
- if (!value) return null;
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 null;
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 null;
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
- * `null` for values without an explicit scheme, since `cbc:EndpointID` requires
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 | null => {
125
+ ): UblEndpoint | undefined => {
126
126
  const normalized = normalizeString(peppolId);
127
- if (!normalized) return null;
127
+ if (!normalized) return undefined;
128
128
  const separatorIndex = normalized.indexOf(":");
129
- if (separatorIndex <= 0) return null;
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 null;
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 | null) =>
154
- value?.toLowerCase().replace(/[^a-z0-9]+/g, "_") ?? null;
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 | null; value: string } | null) => {
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