@financica/ubl 0.8.0 → 0.10.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/README.md +17 -1
- package/dist/build/index.d.ts +210 -171
- package/dist/build/index.d.ts.map +1 -0
- package/dist/build/index.js +681 -595
- package/dist/build/index.js.map +1 -1
- package/dist/index.d.ts +204 -198
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +752 -756
- package/dist/index.js.map +1 -1
- package/package.json +26 -40
package/README.md
CHANGED
|
@@ -139,7 +139,23 @@ const xml = serializeUblDocument(doc);
|
|
|
139
139
|
```
|
|
140
140
|
|
|
141
141
|
Set `documentType: "creditNote"` (with `precedingInvoiceId` referencing the
|
|
142
|
-
original invoice) to emit a `CreditNote` instead.
|
|
142
|
+
original invoice) to emit a `CreditNote` instead.
|
|
143
|
+
|
|
144
|
+
For a document that is already paid, pass the settled gross amount as
|
|
145
|
+
`prepaidAmount` (BT-113) so `payableAmount` (BT-115) reports what is actually
|
|
146
|
+
outstanding rather than the full gross total:
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
const { taxTotal, monetaryTotal } = buildTaxTotals(lines, { prepaidAmount: 121 });
|
|
150
|
+
// monetaryTotal.payableAmount => 0
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
`buildTaxTotals` derives `payableAmount` as
|
|
154
|
+
`taxInclusiveAmount - prepaidAmount + payableRoundingAmount` (BR-CO-16) and does
|
|
155
|
+
not clamp it, so an overpayment shows up as a negative figure instead of being
|
|
156
|
+
silently hidden.
|
|
157
|
+
|
|
158
|
+
The build subpath also exports
|
|
143
159
|
helpers such as `buildSupplierParty`, `buildTaxTotals`, `buildCompanyId`,
|
|
144
160
|
`buildPdfAttachment`, and Peppol identifier utilities (`resolveVatEndpoint`,
|
|
145
161
|
`parsePeppolEndpoint`, `listPeppolReceiverIdentifierCandidates`).
|
package/dist/build/index.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
//#region src/build/ubl/constants.d.ts
|
|
1
2
|
/** Peppol BIS Billing 3.0 / EN 16931 identifiers and fixed code values. */
|
|
2
3
|
/** EN 16931 + Peppol BIS Billing 3.0 customization (BT-24). */
|
|
3
4
|
declare const UBL_CUSTOMIZATION_ID = "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0";
|
|
@@ -17,7 +18,8 @@ declare const NS_INVOICE = "urn:oasis:names:specification:ubl:schema:xsd:Invoice
|
|
|
17
18
|
declare const NS_CREDIT_NOTE = "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2";
|
|
18
19
|
declare const NS_CAC = "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2";
|
|
19
20
|
declare const NS_CBC = "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2";
|
|
20
|
-
|
|
21
|
+
//#endregion
|
|
22
|
+
//#region src/build/ubl/types.d.ts
|
|
21
23
|
/**
|
|
22
24
|
* A vendor-neutral model of a Peppol BIS Billing 3.0 document.
|
|
23
25
|
*
|
|
@@ -27,42 +29,42 @@ declare const NS_CBC = "urn:oasis:names:specification:ubl:schema:xsd:CommonBasic
|
|
|
27
29
|
* populate — not a full UBL object graph.
|
|
28
30
|
*/
|
|
29
31
|
interface UblAddress {
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
32
|
+
/** `cbc:StreetName` (BT-35). */
|
|
33
|
+
street: string | null;
|
|
34
|
+
/** `cbc:AdditionalStreetName` (BT-36). */
|
|
35
|
+
additionalStreet: string | null;
|
|
36
|
+
/** `cbc:CityName` (BT-37). */
|
|
37
|
+
city: string | null;
|
|
38
|
+
/** `cbc:PostalZone` (BT-38). */
|
|
39
|
+
postalZone: string | null;
|
|
40
|
+
/** `cbc:CountrySubentity` (BT-39). */
|
|
41
|
+
countrySubentity: string | null;
|
|
42
|
+
/** `cac:Country/cbc:IdentificationCode` (BT-40) — ISO 3166-1 alpha-2. */
|
|
43
|
+
countryCode: string | null;
|
|
42
44
|
}
|
|
43
45
|
/** Peppol participant identifier, e.g. scheme `0208`, value `0800279001`. */
|
|
44
46
|
interface UblEndpoint {
|
|
45
|
-
|
|
46
|
-
|
|
47
|
+
scheme: string;
|
|
48
|
+
value: string;
|
|
47
49
|
}
|
|
48
50
|
/** Legal registration identifier, e.g. a Belgian enterprise number. */
|
|
49
51
|
interface UblCompanyId {
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
52
|
+
value: string;
|
|
53
|
+
/** ICD scheme (e.g. `0208` for the Belgian CBE), when known. */
|
|
54
|
+
scheme?: string | null;
|
|
53
55
|
}
|
|
54
56
|
interface UblParty {
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
57
|
+
/** `cbc:EndpointID` (BT-49/BT-34) — the Peppol routing identifier. */
|
|
58
|
+
endpoint: UblEndpoint | null;
|
|
59
|
+
/** `cac:PartyName/cbc:Name` (BT-27/BT-44). */
|
|
60
|
+
name: string;
|
|
61
|
+
address: UblAddress;
|
|
62
|
+
/** `cac:PartyTaxScheme/cbc:CompanyID` with `VAT` scheme (BT-31/BT-48). */
|
|
63
|
+
vatNumber: string | null;
|
|
64
|
+
/** `cac:PartyLegalEntity/cbc:RegistrationName` (BT-27/BT-44). Defaults to `name`. */
|
|
65
|
+
legalName: string | null;
|
|
66
|
+
/** `cac:PartyLegalEntity/cbc:CompanyID` (BT-30/BT-47). */
|
|
67
|
+
companyId: UblCompanyId | null;
|
|
66
68
|
}
|
|
67
69
|
/**
|
|
68
70
|
* VAT breakdown category. `id` is a UNCL5305 code:
|
|
@@ -75,86 +77,98 @@ interface UblParty {
|
|
|
75
77
|
* - `G` Export outside the EU
|
|
76
78
|
*/
|
|
77
79
|
interface UblTaxCategory {
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
80
|
+
id: string;
|
|
81
|
+
percent: number;
|
|
82
|
+
/** Required by EN 16931 (BR-E-10/BR-AE-10/…) for non-`S`/`Z` categories. */
|
|
83
|
+
exemptionReason?: string | null;
|
|
82
84
|
}
|
|
83
85
|
interface UblLine {
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
86
|
+
/** `cbc:ID` (BT-126) — line identifier. */
|
|
87
|
+
id: string;
|
|
88
|
+
/** `cac:Item/cbc:Name` (BT-153). */
|
|
89
|
+
name: string;
|
|
90
|
+
/** `cbc:InvoicedQuantity` / `cbc:CreditedQuantity` (BT-129). */
|
|
91
|
+
quantity: number;
|
|
92
|
+
/** UN/ECE Rec 20 unit code (BT-130). */
|
|
93
|
+
unitCode: string;
|
|
94
|
+
/** `cbc:LineExtensionAmount` (BT-131) — net of VAT, after line discounts. */
|
|
95
|
+
lineExtensionAmount: number;
|
|
96
|
+
/** `cac:Price/cbc:PriceAmount` (BT-146) — net unit price. */
|
|
97
|
+
priceAmount: number;
|
|
98
|
+
taxCategory: UblTaxCategory;
|
|
97
99
|
}
|
|
98
100
|
interface UblTaxSubtotal {
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
101
|
+
/** `cbc:TaxableAmount` (BT-116). */
|
|
102
|
+
taxableAmount: number;
|
|
103
|
+
/** `cbc:TaxAmount` (BT-117). */
|
|
104
|
+
taxAmount: number;
|
|
105
|
+
category: UblTaxCategory;
|
|
104
106
|
}
|
|
105
107
|
interface UblTaxTotal {
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
108
|
+
/** `cbc:TaxAmount` (BT-110) — sum of subtotal tax amounts. */
|
|
109
|
+
taxAmount: number;
|
|
110
|
+
subtotals: UblTaxSubtotal[];
|
|
109
111
|
}
|
|
110
112
|
interface UblMonetaryTotal {
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
113
|
+
/** BT-106 — sum of line net amounts. */
|
|
114
|
+
lineExtensionAmount: number;
|
|
115
|
+
/** BT-109 — total without VAT. */
|
|
116
|
+
taxExclusiveAmount: number;
|
|
117
|
+
/** BT-112 — total with VAT. */
|
|
118
|
+
taxInclusiveAmount: number;
|
|
119
|
+
/**
|
|
120
|
+
* BT-113 — sum of amounts paid in advance. **Gross (VAT-inclusive)**, since
|
|
121
|
+
* BR-CO-16 subtracts it directly from BT-112. Omitted when absent or zero.
|
|
122
|
+
*/
|
|
123
|
+
prepaidAmount?: number;
|
|
124
|
+
/** BT-114 — rounding applied to the payable amount. Omitted when absent or zero. */
|
|
125
|
+
payableRoundingAmount?: number;
|
|
126
|
+
/**
|
|
127
|
+
* BT-115 — amount due for payment, i.e. the *outstanding* amount.
|
|
128
|
+
* BR-CO-16: `BT-115 = BT-112 − BT-113 + BT-114`.
|
|
129
|
+
*/
|
|
130
|
+
payableAmount: number;
|
|
119
131
|
}
|
|
120
132
|
/** An embedded supporting document (BG-24), e.g. the rendered PDF. */
|
|
121
133
|
interface UblAttachment {
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
134
|
+
/** `cac:AdditionalDocumentReference/cbc:ID` (BT-122). */
|
|
135
|
+
id: string;
|
|
136
|
+
/** `cbc:EmbeddedDocumentBinaryObject/@filename`. */
|
|
137
|
+
filename: string;
|
|
138
|
+
/** MIME type, e.g. `application/pdf`. */
|
|
139
|
+
mimeCode: string;
|
|
140
|
+
/** Base64-encoded document bytes. */
|
|
141
|
+
base64: string;
|
|
130
142
|
}
|
|
131
143
|
interface UblDocument {
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
144
|
+
documentType: "invoice" | "creditNote";
|
|
145
|
+
/** Invoice / credit note number (BT-1). */
|
|
146
|
+
id: string;
|
|
147
|
+
/** Issue date (BT-2), `YYYY-MM-DD`. */
|
|
148
|
+
issueDate: string;
|
|
149
|
+
/** Payment due date (BT-9). Invoices only. */
|
|
150
|
+
dueDate: string | null;
|
|
151
|
+
/** Free-text note (BT-22). */
|
|
152
|
+
note: string | null;
|
|
153
|
+
/** Document currency (BT-5). */
|
|
154
|
+
currency: string;
|
|
155
|
+
/** Buyer reference (BT-10). */
|
|
156
|
+
buyerReference: string | null;
|
|
157
|
+
/** For credit notes: the referenced original invoice number (BT-25). */
|
|
158
|
+
precedingInvoiceId: string | null;
|
|
159
|
+
supplier: UblParty;
|
|
160
|
+
customer: UblParty;
|
|
161
|
+
lines: UblLine[];
|
|
162
|
+
taxTotal: UblTaxTotal;
|
|
163
|
+
monetaryTotal: UblMonetaryTotal;
|
|
164
|
+
attachments: UblAttachment[];
|
|
153
165
|
}
|
|
154
|
-
|
|
166
|
+
//#endregion
|
|
167
|
+
//#region src/build/ubl/serialize.d.ts
|
|
155
168
|
/** Serialize a {@link UblDocument} into a Peppol BIS Billing 3.0 XML string. */
|
|
156
169
|
declare const serializeUblDocument: (doc: UblDocument) => string;
|
|
157
|
-
|
|
170
|
+
//#endregion
|
|
171
|
+
//#region src/build/party.d.ts
|
|
158
172
|
/**
|
|
159
173
|
* Supplier (seller) VAT status. Drives how zero-VAT lines are reported when the
|
|
160
174
|
* seller does not charge VAT:
|
|
@@ -174,23 +188,23 @@ type SupplierVatStatus = 1 | 2 | 3;
|
|
|
174
188
|
* exists, the party builder no longer needs to know where it came from.
|
|
175
189
|
*/
|
|
176
190
|
interface UblSupplier {
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
191
|
+
/** Display + legal name shown on the invoice. */
|
|
192
|
+
name: string;
|
|
193
|
+
/** ISO 3166-1 alpha-2 country code (e.g. `"BE"`). */
|
|
194
|
+
countryCode: string;
|
|
195
|
+
/**
|
|
196
|
+
* Free-form address. Stripe-style fields (`line1`, `postal_code`, `country`)
|
|
197
|
+
* and legacy/internal fields (`street`, `zip_code`) are both accepted.
|
|
198
|
+
*/
|
|
199
|
+
address: unknown;
|
|
200
|
+
/** Country-specific company/registration number (e.g. BE enterprise number). */
|
|
201
|
+
companyNumber?: string | null;
|
|
202
|
+
/** VAT number with country prefix (e.g. `"BE0793904121"`). */
|
|
203
|
+
vatNumber?: string | null;
|
|
204
|
+
/** Whether the supplier charges VAT. See {@link SupplierVatStatus}. */
|
|
205
|
+
vatStatus: SupplierVatStatus;
|
|
206
|
+
/** Peppol participant identifier in `scheme:value` form (e.g. `"0208:0793904121"`). */
|
|
207
|
+
peppolID?: string | null;
|
|
194
208
|
}
|
|
195
209
|
/** Convert a {@link UblSupplier} into the supplier (seller) party. */
|
|
196
210
|
declare const buildSupplierParty: (supplier: UblSupplier) => UblParty;
|
|
@@ -202,25 +216,25 @@ declare const buildSupplierParty: (supplier: UblSupplier) => UblParty;
|
|
|
202
216
|
* {@link buildCustomerParty}, so the Peppol routing logic lives in one place.
|
|
203
217
|
*/
|
|
204
218
|
interface UblCustomer {
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
219
|
+
/** Display + legal name shown on the invoice. */
|
|
220
|
+
name: string;
|
|
221
|
+
/** Customer address, already normalized by the caller. */
|
|
222
|
+
address: UblAddress;
|
|
223
|
+
/**
|
|
224
|
+
* The customer's ISO 3166-1 alpha-2 country, used to resolve VAT/registration
|
|
225
|
+
* schemes for identifiers that don't carry a country prefix. Pass the
|
|
226
|
+
* customer's *own* country (never the supplier's) so the document is not
|
|
227
|
+
* mis-routed; falls back to the address country when omitted.
|
|
228
|
+
*/
|
|
229
|
+
countryCode?: string | null;
|
|
230
|
+
/** Peppol participant identifier in `scheme:value` form (e.g. `"0208:0793904121"`). */
|
|
231
|
+
peppolID?: string | null;
|
|
232
|
+
/** Global Location Number (resolved under EAS `0088`). */
|
|
233
|
+
glnNumber?: string | null;
|
|
234
|
+
/** Generic tax/registration number (no VAT prefix). */
|
|
235
|
+
taxNumber?: string | null;
|
|
236
|
+
/** VAT number with country prefix (e.g. `"BE0793904121"`). */
|
|
237
|
+
vatNumber?: string | null;
|
|
224
238
|
}
|
|
225
239
|
/**
|
|
226
240
|
* Convert a {@link UblCustomer} into the customer (buyer) party.
|
|
@@ -234,7 +248,8 @@ interface UblCustomer {
|
|
|
234
248
|
* document would be unroutable.
|
|
235
249
|
*/
|
|
236
250
|
declare const buildCustomerParty: (customer: UblCustomer, endpointOverride?: UblEndpoint | null) => UblParty;
|
|
237
|
-
|
|
251
|
+
//#endregion
|
|
252
|
+
//#region src/build/address.d.ts
|
|
238
253
|
/**
|
|
239
254
|
* Normalize a free-form address (Stripe shape, custom shape, or an internal
|
|
240
255
|
* shape) into a {@link UblAddress}.
|
|
@@ -245,24 +260,26 @@ declare const buildCustomerParty: (customer: UblCustomer, endpointOverride?: Ubl
|
|
|
245
260
|
* `null` when "no country" is the right answer.
|
|
246
261
|
*/
|
|
247
262
|
declare const normalizeAddress: (address: unknown, fallbackCountryCode: string | null, fallbackLine?: string | null) => UblAddress;
|
|
248
|
-
|
|
263
|
+
//#endregion
|
|
264
|
+
//#region src/build/attachment.d.ts
|
|
249
265
|
/**
|
|
250
266
|
* Build a UBL embedded-document attachment (BG-24) from raw bytes — e.g. the
|
|
251
267
|
* rendered PDF of the invoice. Emitted as a `cac:AdditionalDocumentReference`
|
|
252
268
|
* with an inline base64 `cbc:EmbeddedDocumentBinaryObject`.
|
|
253
269
|
*/
|
|
254
270
|
declare const buildPdfAttachment: (params: {
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
271
|
+
filename: string;
|
|
272
|
+
bytes: Uint8Array;
|
|
273
|
+
/** Document reference ID (BT-122). Defaults to the filename. */
|
|
274
|
+
id?: string;
|
|
259
275
|
}) => UblAttachment;
|
|
260
276
|
/**
|
|
261
277
|
* Replace each attachment's base64 payload with `[omitted]` plus a length, so a
|
|
262
278
|
* {@link UblDocument} is safe to log or persist for audit.
|
|
263
279
|
*/
|
|
264
280
|
declare const sanitizeUblDocumentForAudit: (doc: UblDocument) => UblDocument;
|
|
265
|
-
|
|
281
|
+
//#endregion
|
|
282
|
+
//#region src/build/identifiers.d.ts
|
|
266
283
|
/**
|
|
267
284
|
* Strip whitespace/punctuation from a country-specific company number.
|
|
268
285
|
* For Belgium, also strips an optional `BE` prefix.
|
|
@@ -281,8 +298,8 @@ declare const normalizeCompanyNumberForCountry: (countryCode: string | null | un
|
|
|
281
298
|
* CompanyID is emitted without a `schemeID` attribute.
|
|
282
299
|
*/
|
|
283
300
|
declare const resolveCompanyIdScheme: (params: {
|
|
284
|
-
|
|
285
|
-
|
|
301
|
+
countryCode: string | null;
|
|
302
|
+
companyNumber: string | null;
|
|
286
303
|
}) => string | null;
|
|
287
304
|
/**
|
|
288
305
|
* Build the `cac:PartyLegalEntity/cbc:CompanyID` value for a party, with the
|
|
@@ -290,8 +307,8 @@ declare const resolveCompanyIdScheme: (params: {
|
|
|
290
307
|
* company number.
|
|
291
308
|
*/
|
|
292
309
|
declare const buildCompanyId: (params: {
|
|
293
|
-
|
|
294
|
-
|
|
310
|
+
countryCode: string | null;
|
|
311
|
+
companyNumber: string | null;
|
|
295
312
|
}) => UblCompanyId | null;
|
|
296
313
|
/**
|
|
297
314
|
* Resolve the Peppol participant identifier for a VAT number, deriving the EAS
|
|
@@ -304,8 +321,8 @@ declare const buildCompanyId: (params: {
|
|
|
304
321
|
* when the country has no VAT EAS scheme or the input is empty.
|
|
305
322
|
*/
|
|
306
323
|
declare const resolveVatEndpoint: (params: {
|
|
307
|
-
|
|
308
|
-
|
|
324
|
+
vatNumber: string | null | undefined;
|
|
325
|
+
countryCode?: string | null;
|
|
309
326
|
}) => UblEndpoint | null;
|
|
310
327
|
/**
|
|
311
328
|
* Parse a Peppol participant identifier into a {@link UblEndpoint}.
|
|
@@ -316,10 +333,10 @@ declare const resolveVatEndpoint: (params: {
|
|
|
316
333
|
*/
|
|
317
334
|
declare const parsePeppolEndpoint: (peppolId: string | null | undefined) => UblEndpoint | null;
|
|
318
335
|
interface CustomerTaxIdentifiers {
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
336
|
+
peppolID: string | null;
|
|
337
|
+
glnNumber: string | null;
|
|
338
|
+
taxNumber: string | null;
|
|
339
|
+
vatNumber: string | null;
|
|
323
340
|
}
|
|
324
341
|
/**
|
|
325
342
|
* Pick the first usable Peppol identifier, GLN, VAT number, and tax number
|
|
@@ -349,40 +366,44 @@ declare const extractCustomerTaxIdentifiers: (taxIds: unknown) => CustomerTaxIde
|
|
|
349
366
|
* identifiers that don't carry a country prefix (GLN, plain tax numbers).
|
|
350
367
|
*/
|
|
351
368
|
declare const listPeppolReceiverIdentifierCandidates: (customer: {
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
369
|
+
peppolID?: string | null;
|
|
370
|
+
glnNumber?: string | null;
|
|
371
|
+
taxNumber?: string | null;
|
|
372
|
+
vatNumber?: string | null;
|
|
356
373
|
}, countryCode?: string | null) => string[];
|
|
357
|
-
|
|
374
|
+
//#endregion
|
|
375
|
+
//#region src/build/numeric.d.ts
|
|
358
376
|
/** Round a number to 2 decimal places (cents). */
|
|
359
377
|
declare const roundCurrency: (value: number) => number;
|
|
360
378
|
/** Convert an integer cent amount into a 2-decimal currency value. */
|
|
361
379
|
declare const centsToDecimal: (cents: number) => number;
|
|
362
|
-
|
|
380
|
+
//#endregion
|
|
381
|
+
//#region src/build/tax-category.d.ts
|
|
363
382
|
/**
|
|
364
383
|
* Stripe Tax `taxability_reason` values that map to a VAT-exempt UBL category
|
|
365
384
|
* (`E`). Reverse charge is handled separately (category `AE`).
|
|
366
385
|
*/
|
|
367
386
|
declare const EXEMPT_TAXABILITY_REASONS: Set<string>;
|
|
368
387
|
interface TaxAmountInfo {
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
388
|
+
amount: number;
|
|
389
|
+
taxability_reason?: string | null;
|
|
390
|
+
tax_rate_percentage?: number | null;
|
|
372
391
|
}
|
|
373
392
|
/**
|
|
374
393
|
* Map an explicit UBL category hint, a Stripe `taxability_reason`, and/or a
|
|
375
394
|
* numeric rate into a {@link UblTaxCategory}.
|
|
376
395
|
*
|
|
377
396
|
* - Reverse charge → `AE` (0%, with exemption reason)
|
|
397
|
+
* - Intra-community supply → `K` (0%, with exemption reason)
|
|
398
|
+
* - Export outside the EU → `G` (0%, with exemption reason)
|
|
378
399
|
* - Any other exempt reason → `E` (0%, with exemption reason)
|
|
379
400
|
* - Category `Z` / rate ≤ 0 → `Z` (zero-rated, 0%)
|
|
380
401
|
* - Otherwise → `S` (standard, the line's rate)
|
|
381
402
|
*/
|
|
382
403
|
declare const taxCategoryFromReasonOrRate: (params: {
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
404
|
+
taxCategoryId?: string | null;
|
|
405
|
+
taxabilityReason: string | null;
|
|
406
|
+
rate: number;
|
|
386
407
|
}) => UblTaxCategory;
|
|
387
408
|
/**
|
|
388
409
|
* Resolve a {@link UblTaxCategory} from a line's Stripe tax info.
|
|
@@ -391,7 +412,8 @@ declare const taxCategoryFromReasonOrRate: (params: {
|
|
|
391
412
|
* otherwise the rate decides standard (`S`) vs zero-rated (`Z`).
|
|
392
413
|
*/
|
|
393
414
|
declare const resolveTaxCategoryFromTaxAmounts: (taxAmounts: TaxAmountInfo[], rate: number) => UblTaxCategory;
|
|
394
|
-
|
|
415
|
+
//#endregion
|
|
416
|
+
//#region src/build/tax-totals.d.ts
|
|
395
417
|
/**
|
|
396
418
|
* Adjust the largest line's net amount so the line nets sum to the
|
|
397
419
|
* authoritative document total (e.g. Stripe's `invoice.total_excluding_tax`).
|
|
@@ -404,8 +426,18 @@ declare const resolveTaxCategoryFromTaxAmounts: (taxAmounts: TaxAmountInfo[], ra
|
|
|
404
426
|
*/
|
|
405
427
|
declare const reconcileLinesToExclTotal: (lines: UblLine[], authoritativeTotalExclVat: number) => UblLine[];
|
|
406
428
|
interface BuildTaxTotalsResult {
|
|
407
|
-
|
|
408
|
-
|
|
429
|
+
taxTotal: UblTaxTotal;
|
|
430
|
+
monetaryTotal: UblMonetaryTotal;
|
|
431
|
+
}
|
|
432
|
+
interface BuildTaxTotalsOptions {
|
|
433
|
+
/**
|
|
434
|
+
* BT-113 — amount already paid, **gross (VAT-inclusive)**. Subtracted from
|
|
435
|
+
* BT-112 to derive the outstanding `payableAmount` (BR-CO-16). Pass the full
|
|
436
|
+
* gross total for a settled document so it reports a payable amount of 0.
|
|
437
|
+
*/
|
|
438
|
+
prepaidAmount?: number;
|
|
439
|
+
/** BT-114 — rounding applied to the payable amount. */
|
|
440
|
+
payableRoundingAmount?: number;
|
|
409
441
|
}
|
|
410
442
|
/**
|
|
411
443
|
* Group lines by `(category, percent)` into a VAT breakdown and compute the
|
|
@@ -417,9 +449,15 @@ interface BuildTaxTotalsResult {
|
|
|
417
449
|
* consistent and passes validation; it can differ by a cent from the figure a
|
|
418
450
|
* payment processor reported, which is an unavoidable artifact of representing
|
|
419
451
|
* a cents-rounded system as a rate-based VAT breakdown.
|
|
452
|
+
*
|
|
453
|
+
* `payableAmount` is derived per BR-CO-16 (`BT-112 − BT-113 + BT-114`) so the
|
|
454
|
+
* invariant holds by construction. The result is *not* clamped: a prepayment
|
|
455
|
+
* exceeding the total yields a negative payable amount, surfacing the upstream
|
|
456
|
+
* overpayment rather than hiding it.
|
|
420
457
|
*/
|
|
421
|
-
declare const buildTaxTotals: (lines: UblLine[]) => BuildTaxTotalsResult;
|
|
422
|
-
|
|
458
|
+
declare const buildTaxTotals: (lines: UblLine[], options?: BuildTaxTotalsOptions) => BuildTaxTotalsResult;
|
|
459
|
+
//#endregion
|
|
460
|
+
//#region src/build/xml.d.ts
|
|
423
461
|
/**
|
|
424
462
|
* Minimal, dependency-free XML builder + serializer.
|
|
425
463
|
*
|
|
@@ -430,12 +468,12 @@ declare const buildTaxTotals: (lines: UblLine[]) => BuildTaxTotalsResult;
|
|
|
430
468
|
*/
|
|
431
469
|
type XmlAttrs = Record<string, string | number | null | undefined>;
|
|
432
470
|
interface XmlElement {
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
471
|
+
name: string;
|
|
472
|
+
attrs?: XmlAttrs;
|
|
473
|
+
/** Leaf text content. Mutually exclusive with `children`. */
|
|
474
|
+
text?: string | number | null;
|
|
475
|
+
/** Child elements. Mutually exclusive with `text`. */
|
|
476
|
+
children?: XmlElement[];
|
|
439
477
|
}
|
|
440
478
|
/** Falsy children are dropped, so callers can write `cond && el(...)`. */
|
|
441
479
|
type ChildSpec = XmlElement | null | undefined | false;
|
|
@@ -449,5 +487,6 @@ type ChildSpec = XmlElement | null | undefined | false;
|
|
|
449
487
|
declare const el: (name: string, attrs?: XmlAttrs | null, content?: string | number | null | ChildSpec[]) => XmlElement;
|
|
450
488
|
/** Serialize a root element into a UTF-8 XML document string. */
|
|
451
489
|
declare const serializeDocument: (root: XmlElement) => string;
|
|
452
|
-
|
|
453
|
-
export { type BuildTaxTotalsResult, COUNTRY_CODE_LIST_ID, CREDIT_NOTE_TYPE_CODE, type CustomerTaxIdentifiers, DEFAULT_UNIT_CODE, EXEMPT_TAXABILITY_REASONS, INVOICE_TYPE_CODE, NS_CAC, NS_CBC, NS_CREDIT_NOTE, NS_INVOICE, type SupplierVatStatus, type TaxAmountInfo, UBL_CUSTOMIZATION_ID, UBL_PROFILE_ID, type UblAddress, type UblAttachment, type UblCompanyId, type UblCustomer, type UblDocument, type UblEndpoint, type UblLine, type UblMonetaryTotal, type UblParty, type UblSupplier, type UblTaxCategory, type UblTaxSubtotal, type UblTaxTotal, VAT_TAX_SCHEME_ID, type XmlAttrs, type XmlElement, buildCompanyId, buildCustomerParty, buildPdfAttachment, buildSupplierParty, buildTaxTotals, centsToDecimal, el, extractCustomerTaxIdentifiers, listPeppolReceiverIdentifierCandidates, normalizeAddress, normalizeCompanyNumberForCountry, parsePeppolEndpoint, reconcileLinesToExclTotal, resolveCompanyIdScheme, resolveTaxCategoryFromTaxAmounts, resolveVatEndpoint, roundCurrency, sanitizeUblDocumentForAudit, serializeDocument, serializeUblDocument, taxCategoryFromReasonOrRate };
|
|
490
|
+
//#endregion
|
|
491
|
+
export { type BuildTaxTotalsOptions, type BuildTaxTotalsResult, COUNTRY_CODE_LIST_ID, CREDIT_NOTE_TYPE_CODE, type CustomerTaxIdentifiers, DEFAULT_UNIT_CODE, EXEMPT_TAXABILITY_REASONS, INVOICE_TYPE_CODE, NS_CAC, NS_CBC, NS_CREDIT_NOTE, NS_INVOICE, type SupplierVatStatus, type TaxAmountInfo, UBL_CUSTOMIZATION_ID, UBL_PROFILE_ID, type UblAddress, type UblAttachment, type UblCompanyId, type UblCustomer, type UblDocument, type UblEndpoint, type UblLine, type UblMonetaryTotal, type UblParty, type UblSupplier, type UblTaxCategory, type UblTaxSubtotal, type UblTaxTotal, VAT_TAX_SCHEME_ID, type XmlAttrs, type XmlElement, buildCompanyId, buildCustomerParty, buildPdfAttachment, buildSupplierParty, buildTaxTotals, centsToDecimal, el, extractCustomerTaxIdentifiers, listPeppolReceiverIdentifierCandidates, normalizeAddress, normalizeCompanyNumberForCountry, parsePeppolEndpoint, reconcileLinesToExclTotal, resolveCompanyIdScheme, resolveTaxCategoryFromTaxAmounts, resolveVatEndpoint, roundCurrency, sanitizeUblDocumentForAudit, serializeDocument, serializeUblDocument, taxCategoryFromReasonOrRate };
|
|
492
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/build/ubl/constants.ts","../../src/build/ubl/types.ts","../../src/build/ubl/serialize.ts","../../src/build/party.ts","../../src/build/address.ts","../../src/build/attachment.ts","../../src/build/identifiers.ts","../../src/build/numeric.ts","../../src/build/tax-category.ts","../../src/build/tax-totals.ts","../../src/build/xml.ts"],"mappings":";;;cAGa;;cAIA;;cAGA;;cAEA;;cAGA;;cAGA;;cAGA;cAEA;cACA;cAEA;cAEA;;;;;;;;;;;UCnBI;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;UAIgB;EAChB;EACA;;;UAIgB;EAChB;;EAEA;;UAGgB;;EAEhB,UAAU;;EAEV;EACA,SAAS;;EAET;;EAEA;;EAEA,WAAW;;;;;;;;;;;;UAaK;EAChB;EACA;;EAEA;;UAGgB;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;EACA,aAAa;;UAGG;;EAEhB;;EAEA;EACA,UAAU;;UAGM;;EAEhB;EACA,WAAW;;UAGK;;EAEhB;;EAEA;;EAEA;;;;;EAKA;;EAEA;;;;;EAKA;;;UAIgB;;EAEhB;;EAEA;;EAEA;;EAEA;;UAGgB;EAChB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;EACA,UAAU;EACV,UAAU;EACV,OAAO;EACP,UAAU;EACV,eAAe;EACf,aAAa;;;;;cCyBD,uBAAoB,KAAS;;;;;;;;;;;;;;KCjK9B;;;;;;;UAQK;;EAEhB;;EAEA;;;;;EAKA;;EAEA;;EAEA;;EAEA,WAAW;;EAEX;;;cAIY,qBAAkB,UAAc,gBAAc;;;;;;;;UAsB1C;;EAEhB;;EAEA,SAAS;;;;;;;EAOT;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;cAcY,qBAAkB,UACpB,aAAW,mBACF,uBACjB;;;;;;;;;;;;cCrFU,mBAAgB,kBACZ,oCACkB,iCAEhC;;;;;;;;cCfU,qBAAkB;EAC9B;EACA,OAAO;;EAEP;MACG;;;;;cAWS,8BAA2B,KAAS,gBAAc;;;;;;;cCLlD,mCAAgC,wCACN;;;;;;;;;;;;;cAqB1B,yBAAsB;EAClC;EACA;;;;;;;cA0BY,iBAAc;EAC1B;EACA;MACG;;;;;;;;;;;cAkFS,qBAAkB;EAC9B;EACA;MACG;;;;;;;;cA2BS,sBAAmB,wCAE7B;UAWc;EAChB;EACA;EACA;EACA;;;;;;;;;cAaY,gCAA6B,oBAEvC;;;;;;;;;;;;;;;;;;;;cAwDU,yCAAsC;EAEjD;EACA;EACA;EACA;GACA;;;;cCpRW,gBAAa;;cAIb,iBAAc;;;;;;;cCCd,2BAAyB;UAsBrB;EAChB;EACA;EACA;;;;;;;;;;;;;cAoBY,8BAA2B;EACvC;EACA;EACA;MACG;;;;;;;cA6CS,mCAAgC,YAChC,iBAAe,iBAEzB;;;;;;;;;;;;;cCpFU,4BAAyB,OAC9B,WAAS,sCAEd;UA8Bc;EAChB,UAAU;EACV,eAAe;;UAGC;;;;;;EAMhB;;EAEA;;;;;;;;;;;;;;;;;;cAmBY,iBAAc,OACnB,WAAS,UACN,0BACR;;;;;;;;;;;KC9ES,WAAW;UAEN;EAChB;EACA,QAAQ;;EAER;;EAEA,WAAW;;;KAIP,YAAY;;;;;;;;cASJ,KAAE,cACF,QACJ,iBAAe,mCACY,gBACjC;;cA4CU,oBAAiB,MAAU"}
|