@financica/ubl 0.15.0 → 0.16.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/dist/index.d.ts CHANGED
@@ -1,154 +1,154 @@
1
1
  //#region src/types.d.ts
2
2
  interface UblAddress {
3
- street: string;
4
- additionalStreet?: string;
5
- city: string;
6
- postalZone: string;
7
- countrySubentity?: string;
8
- countryCode: string;
3
+ street?: string | undefined;
4
+ additionalStreet?: string | undefined;
5
+ city?: string | undefined;
6
+ postalZone?: string | undefined;
7
+ countrySubentity?: string | undefined;
8
+ countryCode?: string | undefined;
9
9
  }
10
10
  interface UblContact {
11
- name?: string;
12
- phone?: string;
13
- email?: string;
11
+ name?: string | undefined;
12
+ phone?: string | undefined;
13
+ email?: string | undefined;
14
14
  }
15
15
  interface UblPartyIdentification {
16
16
  id: string;
17
- schemeId?: string;
17
+ schemeId?: string | undefined;
18
18
  }
19
19
  interface UblParty {
20
- name: string;
21
- registrationName?: string;
22
- companyLegalForm?: string;
23
- vatId?: string;
24
- taxSchemeId?: string;
25
- companyId?: string;
26
- companyIdSchemeId?: string;
27
- endpointId?: string;
28
- endpointSchemeId?: string;
29
- partyIdentifications?: UblPartyIdentification[];
30
- address?: UblAddress;
31
- contact?: UblContact;
20
+ name?: string | undefined;
21
+ registrationName?: string | undefined;
22
+ companyLegalForm?: string | undefined;
23
+ vatId?: string | undefined;
24
+ taxSchemeId?: string | undefined;
25
+ companyId?: string | undefined;
26
+ companyIdSchemeId?: string | undefined;
27
+ endpointId?: string | undefined;
28
+ endpointSchemeId?: string | undefined;
29
+ partyIdentifications?: UblPartyIdentification[] | undefined;
30
+ address?: UblAddress | undefined;
31
+ contact?: UblContact | undefined;
32
32
  }
33
33
  interface UblItemProperty {
34
34
  name: string;
35
- value: string;
35
+ value?: string | undefined;
36
36
  }
37
37
  interface UblLine {
38
38
  id: string;
39
- description: string;
40
- quantity: number;
41
- unitCode: string;
42
- unitPrice: number;
43
- lineExtensionAmount: number;
44
- taxPercent?: number;
45
- taxAmount?: number;
46
- taxCategoryId?: string;
47
- taxSchemeId?: string;
48
- taxSubtotals?: UblTaxSubtotal[];
49
- allowanceCharges?: UblAllowanceCharge[];
50
- discountAmount?: number;
51
- chargeAmount?: number;
52
- itemName?: string;
53
- sellersItemId?: string;
54
- buyersItemId?: string;
55
- additionalItemProperties?: UblItemProperty[];
39
+ description?: string | undefined;
40
+ quantity?: number | undefined;
41
+ unitCode?: string | undefined;
42
+ unitPrice?: number | undefined;
43
+ lineExtensionAmount?: number | undefined;
44
+ taxPercent?: number | undefined;
45
+ taxAmount?: number | undefined;
46
+ taxCategoryId?: string | undefined;
47
+ taxSchemeId?: string | undefined;
48
+ taxSubtotals?: UblTaxSubtotal[] | undefined;
49
+ allowanceCharges?: UblAllowanceCharge[] | undefined;
50
+ discountAmount?: number | undefined;
51
+ chargeAmount?: number | undefined;
52
+ itemName?: string | undefined;
53
+ sellersItemId?: string | undefined;
54
+ buyersItemId?: string | undefined;
55
+ additionalItemProperties?: UblItemProperty[] | undefined;
56
56
  /** EN 16931 BT-134/BT-135: the line's own service period. */
57
- invoicePeriod?: UblInvoicePeriod;
57
+ invoicePeriod?: UblInvoicePeriod | undefined;
58
58
  }
59
59
  interface UblAllowanceCharge {
60
60
  chargeIndicator: boolean;
61
- amount: number;
62
- baseAmount?: number;
63
- multiplierFactorNumeric?: number;
64
- reason?: string;
65
- reasonCode?: string;
66
- taxPercent?: number;
67
- taxCategoryId?: string;
68
- taxSchemeId?: string;
61
+ amount?: number | undefined;
62
+ baseAmount?: number | undefined;
63
+ multiplierFactorNumeric?: number | undefined;
64
+ reason?: string | undefined;
65
+ reasonCode?: string | undefined;
66
+ taxPercent?: number | undefined;
67
+ taxCategoryId?: string | undefined;
68
+ taxSchemeId?: string | undefined;
69
69
  }
70
70
  interface UblTaxSubtotal {
71
- taxableAmount: number;
72
- taxAmount: number;
73
- taxPercent: number;
74
- taxCategoryId?: string;
75
- taxSchemeId?: string;
76
- taxExemptionReason?: string;
71
+ taxableAmount?: number | undefined;
72
+ taxAmount?: number | undefined;
73
+ taxPercent?: number | undefined;
74
+ taxCategoryId?: string | undefined;
75
+ taxSchemeId?: string | undefined;
76
+ taxExemptionReason?: string | undefined;
77
77
  }
78
78
  interface UblMonetaryTotal {
79
- lineExtensionAmount: number;
80
- taxExclusiveAmount: number;
81
- taxInclusiveAmount: number;
82
- allowanceTotalAmount?: number;
83
- chargeTotalAmount?: number;
84
- prepaidAmount?: number;
85
- payableRoundingAmount?: number;
86
- payableAmount: number;
79
+ lineExtensionAmount?: number | undefined;
80
+ taxExclusiveAmount?: number | undefined;
81
+ taxInclusiveAmount?: number | undefined;
82
+ allowanceTotalAmount?: number | undefined;
83
+ chargeTotalAmount?: number | undefined;
84
+ prepaidAmount?: number | undefined;
85
+ payableRoundingAmount?: number | undefined;
86
+ payableAmount?: number | undefined;
87
87
  }
88
88
  interface UblPaymentMeans {
89
- code: string;
90
- codeName?: string;
91
- paymentId?: string;
92
- iban?: string;
93
- bic?: string;
94
- accountName?: string;
95
- mandateId?: string;
89
+ code?: string | undefined;
90
+ codeName?: string | undefined;
91
+ paymentId?: string | undefined;
92
+ iban?: string | undefined;
93
+ bic?: string | undefined;
94
+ accountName?: string | undefined;
95
+ mandateId?: string | undefined;
96
96
  }
97
97
  interface UblInvoicePeriod {
98
- startDate?: string;
99
- endDate?: string;
100
- descriptionCode?: string;
98
+ startDate?: string | undefined;
99
+ endDate?: string | undefined;
100
+ descriptionCode?: string | undefined;
101
101
  }
102
102
  interface UblAttachment {
103
- id: string;
104
- filename?: string;
105
- mimeCode?: string;
106
- description?: string;
107
- base64Content?: string;
108
- externalUri?: string;
103
+ id?: string | undefined;
104
+ filename?: string | undefined;
105
+ mimeCode?: string | undefined;
106
+ description?: string | undefined;
107
+ base64Content?: string | undefined;
108
+ externalUri?: string | undefined;
109
109
  }
110
110
  interface UblDocumentReference {
111
- id: string;
112
- description?: string;
111
+ id?: string | undefined;
112
+ description?: string | undefined;
113
113
  }
114
114
  interface UblDelivery {
115
- actualDeliveryDate?: string;
116
- address?: UblAddress;
115
+ actualDeliveryDate?: string | undefined;
116
+ address?: UblAddress | undefined;
117
117
  }
118
118
  interface UblBillingReference {
119
- invoiceId?: string;
120
- invoiceIssueDate?: string;
119
+ invoiceId?: string | undefined;
120
+ invoiceIssueDate?: string | undefined;
121
121
  }
122
122
  interface UblInvoice {
123
123
  documentType: "Invoice" | "CreditNote";
124
- customizationId?: string;
125
- profileId?: string;
124
+ customizationId?: string | undefined;
125
+ profileId?: string | undefined;
126
126
  id: string;
127
- invoiceTypeCode?: string;
127
+ invoiceTypeCode?: string | undefined;
128
128
  issueDate: string;
129
- dueDate?: string;
130
- taxPointDate?: string;
129
+ dueDate?: string | undefined;
130
+ taxPointDate?: string | undefined;
131
131
  currency: string;
132
- buyerReference?: string;
133
- orderReference?: string;
134
- salesOrderId?: string;
135
- contractReference?: string;
136
- projectReference?: string;
137
- billingReference?: UblBillingReference;
132
+ buyerReference?: string | undefined;
133
+ orderReference?: string | undefined;
134
+ salesOrderId?: string | undefined;
135
+ contractReference?: string | undefined;
136
+ projectReference?: string | undefined;
137
+ billingReference?: UblBillingReference | undefined;
138
138
  seller: UblParty;
139
139
  buyer: UblParty;
140
- delivery?: UblDelivery;
140
+ delivery?: UblDelivery | undefined;
141
141
  lines: UblLine[];
142
142
  taxSubtotals: UblTaxSubtotal[];
143
143
  monetaryTotal: UblMonetaryTotal;
144
- paymentMeans?: UblPaymentMeans;
145
- paymentMeansList?: UblPaymentMeans[];
146
- invoicePeriod?: UblInvoicePeriod;
147
- note?: string;
148
- paymentTermsNote?: string;
149
- attachments?: UblAttachment[];
150
- documentReferences?: UblDocumentReference[];
151
- allowanceCharges?: UblAllowanceCharge[];
144
+ paymentMeans?: UblPaymentMeans | undefined;
145
+ paymentMeansList?: UblPaymentMeans[] | undefined;
146
+ invoicePeriod?: UblInvoicePeriod | undefined;
147
+ note?: string | undefined;
148
+ paymentTermsNote?: string | undefined;
149
+ attachments?: UblAttachment[] | undefined;
150
+ documentReferences?: UblDocumentReference[] | undefined;
151
+ allowanceCharges?: UblAllowanceCharge[] | undefined;
152
152
  }
153
153
  interface InvoiceExtractionDTO {
154
154
  provider: string;
@@ -211,10 +211,10 @@ interface InvoiceExtractionDTO {
211
211
  /**
212
212
  * An embedded attachment extracted from a UBL document's
213
213
  * `AdditionalDocumentReference` entries, with its binary content still
214
- * base64-encoded. `sizeBytes` is the approximate decoded size.
214
+ * base64-encoded. `sizeBytes` is the decoded size.
215
215
  */
216
216
  interface UblEmbeddedAttachment {
217
- id: string | null;
217
+ id?: string | undefined;
218
218
  filename: string;
219
219
  mimeCode: string;
220
220
  sizeBytes: number;
@@ -227,6 +227,8 @@ interface UblEmbeddedAttachment {
227
227
  * UBL invoice or credit note XML. Attachments referenced only by external URI
228
228
  * (no `EmbeddedDocumentBinaryObject`) are skipped; use {@link parseUblInvoice}
229
229
  * directly when those matter.
230
+ *
231
+ * @throws {UblParseError} when the XML is malformed or not a UBL invoice.
230
232
  */
231
233
  declare const extractUblEmbeddedAttachments: (xml: string) => UblEmbeddedAttachment[];
232
234
  /**
@@ -235,7 +237,29 @@ declare const extractUblEmbeddedAttachments: (xml: string) => UblEmbeddedAttachm
235
237
  */
236
238
  declare const isPdfLikeAttachment: (attachment: Pick<UblAttachment, "filename" | "mimeCode">) => boolean;
237
239
  //#endregion
240
+ //#region src/errors.d.ts
241
+ /**
242
+ * Thrown by the parse side of this package when input is broken: malformed
243
+ * XML, or a UBL document missing an element EN 16931 makes mandatory. A parser
244
+ * returns `null` instead when the input is well-formed but not the document
245
+ * type it parses.
246
+ */
247
+ declare class UblParseError extends Error {
248
+ readonly cause?: unknown;
249
+ constructor(message: string, options?: {
250
+ cause?: unknown;
251
+ });
252
+ }
253
+ //#endregion
238
254
  //#region src/parser.d.ts
255
+ /**
256
+ * Parse a UBL 2.1 Invoice or CreditNote.
257
+ *
258
+ * Returns `null` when the XML is well-formed but its root is not a UBL
259
+ * `Invoice`/`CreditNote`. Throws {@link UblParseError} when the XML is
260
+ * malformed or the document lacks an element EN 16931 makes mandatory
261
+ * (document id, issue date, currency, line id).
262
+ */
239
263
  declare function parseUblInvoice(xml: string): UblInvoice | null;
240
264
  //#endregion
241
265
  //#region src/mlr.d.ts
@@ -248,21 +272,22 @@ declare const PEPPOL_MLR_DOCUMENT_TYPE_VALUE = "urn:oasis:names:specification:ub
248
272
  declare const PEPPOL_MLR_PROCESS_VALUE = "urn:fdc:peppol.eu:poacc:bis:mlr:3";
249
273
  /**
250
274
  * A parsed Peppol Message Level Response (a UBL `ApplicationResponse`). Every
251
- * field is nullable: a given MLR may omit any of them.
275
+ * field is optional: a given MLR may omit any of them, and an omitted field is
276
+ * an absent key.
252
277
  */
253
278
  interface PeppolMessageLevelResponse {
254
- customizationId: string | null;
255
- profileId: string | null;
256
- responseId: string | null;
257
- issueDate: string | null;
258
- issueTime: string | null;
259
- referencedDocumentId: string | null;
260
- responseCode: string | null;
261
- description: string | null;
279
+ customizationId?: string | undefined;
280
+ profileId?: string | undefined;
281
+ responseId?: string | undefined;
282
+ issueDate?: string | undefined;
283
+ issueTime?: string | undefined;
284
+ referencedDocumentId?: string | undefined;
285
+ responseCode?: string | undefined;
286
+ description?: string | undefined;
262
287
  /** Sender participant id as `schemeID:value` (e.g. `0208:0793904121`). */
263
- senderIdentifier: string | null;
288
+ senderIdentifier?: string | undefined;
264
289
  /** Receiver participant id as `schemeID:value`. */
265
- receiverIdentifier: string | null;
290
+ receiverIdentifier?: string | undefined;
266
291
  }
267
292
  /**
268
293
  * Whether an inbound document is a Peppol Message Level Response, identified by
@@ -276,8 +301,8 @@ declare const isPeppolMessageLevelResponse: (params: {
276
301
  }) => boolean;
277
302
  /**
278
303
  * Parse a Peppol Message Level Response (UBL `ApplicationResponse`), unwrapping
279
- * an SBDH envelope when present. Throws when the XML is not an
280
- * ApplicationResponse.
304
+ * an SBDH envelope when present. Throws {@link UblParseError} when the XML is
305
+ * malformed or is not an ApplicationResponse.
281
306
  */
282
307
  declare const parsePeppolMessageLevelResponse: (xml: string) => PeppolMessageLevelResponse;
283
308
  //#endregion
@@ -291,6 +316,9 @@ declare const decodeXmlBytes: (bytes: Uint8Array) => string;
291
316
  /**
292
317
  * Parse a UBL XML string and normalize it into a flat DTO suitable for
293
318
  * database storage or API responses.
319
+ *
320
+ * @throws {UblParseError} when the XML is malformed, not a UBL invoice, or
321
+ * lacks a mandatory element.
294
322
  */
295
323
  declare const normalizeUblResponse: (xml: string, documentId: string) => {
296
324
  extracted: InvoiceExtractionDTO;
@@ -311,5 +339,5 @@ declare const parseUblInvoiceDocument: (params: {
311
339
  providerJobId: string | null;
312
340
  };
313
341
  //#endregion
314
- export { type InvoiceExtractionDTO, PEPPOL_MLR_DOCUMENT_TYPE_VALUE, PEPPOL_MLR_PROCESS_VALUE, type PeppolMessageLevelResponse, type UblAddress, type UblAllowanceCharge, type UblAttachment, type UblBillingReference, type UblContact, type UblDelivery, type UblDocumentReference, type UblEmbeddedAttachment, type UblInvoice, type UblInvoicePeriod, type UblItemProperty, type UblLine, type UblMonetaryTotal, type UblParty, type UblPartyIdentification, type UblPaymentMeans, type UblTaxSubtotal, decodeXmlBytes, extractUblEmbeddedAttachments, isPdfLikeAttachment, isPeppolMessageLevelResponse, normalizeCurrency, normalizeUblResponse, parseDate, parsePeppolMessageLevelResponse, parseUblInvoice, parseUblInvoiceDocument };
342
+ export { type InvoiceExtractionDTO, PEPPOL_MLR_DOCUMENT_TYPE_VALUE, PEPPOL_MLR_PROCESS_VALUE, type PeppolMessageLevelResponse, type UblAddress, type UblAllowanceCharge, type UblAttachment, type UblBillingReference, type UblContact, type UblDelivery, type UblDocumentReference, type UblEmbeddedAttachment, type UblInvoice, type UblInvoicePeriod, type UblItemProperty, type UblLine, type UblMonetaryTotal, UblParseError, type UblParty, type UblPartyIdentification, type UblPaymentMeans, type UblTaxSubtotal, decodeXmlBytes, extractUblEmbeddedAttachments, isPdfLikeAttachment, isPeppolMessageLevelResponse, normalizeCurrency, normalizeUblResponse, parseDate, parsePeppolMessageLevelResponse, parseUblInvoice, parseUblInvoiceDocument };
315
343
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/attachments.ts","../src/parser.ts","../src/mlr.ts","../src/normalize.ts"],"mappings":";UAEiB;EAChB;EACA;EACA;EACA;EACA;EACA;;UAGgB;EAChB;EACA;EACA;;UAGgB;EAChB;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,uBAAuB;EACvB,UAAU;EACV,UAAU;;UAGM;EAChB;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,eAAe;EACf,mBAAmB;EACnB;EACA;EACA;EACA;EACA;EACA,2BAA2B;;EAE3B,gBAAgB;;UAGA;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;;UAGgB;EAChB;EACA;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;;UAGgB;EAChB;EACA;;UAGgB;EAChB;EACA,UAAU;;UAGM;EAChB;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,mBAAmB;EACnB,QAAQ;EACR,OAAO;EACP,WAAW;EACX,OAAO;EACP,cAAc;EACd,eAAe;EACf,eAAe;EACf,mBAAmB;EACnB,gBAAgB;EAChB;EACA;EACA,cAAc;EACd,qBAAqB;EACrB,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;;;;;;;;;;UCxNO;EAChB;EACA;EACA;EACA;;EAEA;EACA;;;;;;;;cAYY,gCAA6B,gBAAkB;;;;;cAwB/C,sBAAmB,YACnB,KAAK;;;iBCycF,gBAAgB,cAAc;;;;;;;cCnfjC;;cAIA;;;;;UAMI;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;EAEA;;;;;;;cA8FY,+BAA4B;EACxC;EACA;EACA;;;;;;;cAgBY,kCAA+B,gBAEzC;;;cCxHU,oBAAiB;cAOjB,YAAS;;;;cAmHT,iBAAc,OAAW;;;;;cASzB,uBAAoB,aACrB;EAGX,WAAW;EACX,YAAY;;;;;cA4OA,0BAAuB;EACnC,OAAO;EACP;EACA;;;;;aAFO;EAYiB"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/attachments.ts","../src/errors.ts","../src/parser.ts","../src/mlr.ts","../src/normalize.ts"],"mappings":";UASiB;EAChB;EACA;EACA;EACA;EACA;EACA;;UAGgB;EAChB;EACA;EACA;;UAGgB;EAChB;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,uBAAuB;EACvB,UAAU;EACV,UAAU;;UAGM;EAChB;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,eAAe;EACf,mBAAmB;EACnB;EACA;EACA;EACA;EACA;EACA,2BAA2B;;EAE3B,gBAAgB;;UAGA;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;;UAGgB;EAChB;EACA;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;;UAGgB;EAChB;EACA;;UAGgB;EAChB;EACA,UAAU;;UAGM;EAChB;EACA;;UAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,mBAAmB;EACnB,QAAQ;EACR,OAAO;EACP,WAAW;EACX,OAAO;EACP,cAAc;EACd,eAAe;EACf,eAAe;EACf,mBAAmB;EACnB,gBAAgB;EAChB;EACA;EACA,cAAc;EACd,qBAAqB;EACrB,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;;;;;;;;;;UC9NO;EAChB;EACA;EACA;EACA;;EAEA;EACA;;;;;;;;;;cAmBY,gCAA6B,gBAAkB;;;;;cAyB/C,sBAAmB,YACnB,KAAK;;;;;;;;;cCvDL,sBAAsB;WAChB;EAElB,YAAY,iBAAiB;IAAY;;;;;;;;;;;;;iBCygB1B,gBAAgB,cAAc;;;;;;;cC1gBjC;;cAIA;;;;;;UAOI;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;EAEA;;;;;;;cAuEY,+BAA4B;EACxC;EACA;EACA;;;;;;;cAsBY,kCAA+B,gBAEzC;;;cCpGU,oBAAiB;cAOjB,YAAS;;;;cAsHT,iBAAc,OAAW;;;;;;;;cAYzB,uBAAoB,aACrB;EAGX,WAAW;EACX,YAAY;;;;;cA4NA,0BAAuB;EACnC,OAAO;EACP;EACA;;;;;aAFO;EAYiB"}