@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 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. The build subpath also exports
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`).
@@ -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
- /** `cbc:StreetName` (BT-35). */
31
- street: string | null;
32
- /** `cbc:AdditionalStreetName` (BT-36). */
33
- additionalStreet: string | null;
34
- /** `cbc:CityName` (BT-37). */
35
- city: string | null;
36
- /** `cbc:PostalZone` (BT-38). */
37
- postalZone: string | null;
38
- /** `cbc:CountrySubentity` (BT-39). */
39
- countrySubentity: string | null;
40
- /** `cac:Country/cbc:IdentificationCode` (BT-40) — ISO 3166-1 alpha-2. */
41
- countryCode: string | null;
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
- scheme: string;
46
- value: string;
47
+ scheme: string;
48
+ value: string;
47
49
  }
48
50
  /** Legal registration identifier, e.g. a Belgian enterprise number. */
49
51
  interface UblCompanyId {
50
- value: string;
51
- /** ICD scheme (e.g. `0208` for the Belgian CBE), when known. */
52
- scheme?: string | null;
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
- /** `cbc:EndpointID` (BT-49/BT-34) — the Peppol routing identifier. */
56
- endpoint: UblEndpoint | null;
57
- /** `cac:PartyName/cbc:Name` (BT-27/BT-44). */
58
- name: string;
59
- address: UblAddress;
60
- /** `cac:PartyTaxScheme/cbc:CompanyID` with `VAT` scheme (BT-31/BT-48). */
61
- vatNumber: string | null;
62
- /** `cac:PartyLegalEntity/cbc:RegistrationName` (BT-27/BT-44). Defaults to `name`. */
63
- legalName: string | null;
64
- /** `cac:PartyLegalEntity/cbc:CompanyID` (BT-30/BT-47). */
65
- companyId: UblCompanyId | null;
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
- id: string;
79
- percent: number;
80
- /** Required by EN 16931 (BR-E-10/BR-AE-10/…) for non-`S`/`Z` categories. */
81
- exemptionReason?: string | null;
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
- /** `cbc:ID` (BT-126) — line identifier. */
85
- id: string;
86
- /** `cac:Item/cbc:Name` (BT-153). */
87
- name: string;
88
- /** `cbc:InvoicedQuantity` / `cbc:CreditedQuantity` (BT-129). */
89
- quantity: number;
90
- /** UN/ECE Rec 20 unit code (BT-130). */
91
- unitCode: string;
92
- /** `cbc:LineExtensionAmount` (BT-131) — net of VAT, after line discounts. */
93
- lineExtensionAmount: number;
94
- /** `cac:Price/cbc:PriceAmount` (BT-146) — net unit price. */
95
- priceAmount: number;
96
- taxCategory: UblTaxCategory;
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
- /** `cbc:TaxableAmount` (BT-116). */
100
- taxableAmount: number;
101
- /** `cbc:TaxAmount` (BT-117). */
102
- taxAmount: number;
103
- category: UblTaxCategory;
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
- /** `cbc:TaxAmount` (BT-110) — sum of subtotal tax amounts. */
107
- taxAmount: number;
108
- subtotals: UblTaxSubtotal[];
108
+ /** `cbc:TaxAmount` (BT-110) — sum of subtotal tax amounts. */
109
+ taxAmount: number;
110
+ subtotals: UblTaxSubtotal[];
109
111
  }
110
112
  interface UblMonetaryTotal {
111
- /** BT-106 — sum of line net amounts. */
112
- lineExtensionAmount: number;
113
- /** BT-109 — total without VAT. */
114
- taxExclusiveAmount: number;
115
- /** BT-112 — total with VAT. */
116
- taxInclusiveAmount: number;
117
- /** BT-115 — amount due for payment. */
118
- payableAmount: number;
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
- /** `cac:AdditionalDocumentReference/cbc:ID` (BT-122). */
123
- id: string;
124
- /** `cbc:EmbeddedDocumentBinaryObject/@filename`. */
125
- filename: string;
126
- /** MIME type, e.g. `application/pdf`. */
127
- mimeCode: string;
128
- /** Base64-encoded document bytes. */
129
- base64: string;
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
- documentType: "invoice" | "creditNote";
133
- /** Invoice / credit note number (BT-1). */
134
- id: string;
135
- /** Issue date (BT-2), `YYYY-MM-DD`. */
136
- issueDate: string;
137
- /** Payment due date (BT-9). Invoices only. */
138
- dueDate: string | null;
139
- /** Free-text note (BT-22). */
140
- note: string | null;
141
- /** Document currency (BT-5). */
142
- currency: string;
143
- /** Buyer reference (BT-10). */
144
- buyerReference: string | null;
145
- /** For credit notes: the referenced original invoice number (BT-25). */
146
- precedingInvoiceId: string | null;
147
- supplier: UblParty;
148
- customer: UblParty;
149
- lines: UblLine[];
150
- taxTotal: UblTaxTotal;
151
- monetaryTotal: UblMonetaryTotal;
152
- attachments: UblAttachment[];
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
- /** Display + legal name shown on the invoice. */
178
- name: string;
179
- /** ISO 3166-1 alpha-2 country code (e.g. `"BE"`). */
180
- countryCode: string;
181
- /**
182
- * Free-form address. Stripe-style fields (`line1`, `postal_code`, `country`)
183
- * and legacy/internal fields (`street`, `zip_code`) are both accepted.
184
- */
185
- address: unknown;
186
- /** Country-specific company/registration number (e.g. BE enterprise number). */
187
- companyNumber?: string | null;
188
- /** VAT number with country prefix (e.g. `"BE0793904121"`). */
189
- vatNumber?: string | null;
190
- /** Whether the supplier charges VAT. See {@link SupplierVatStatus}. */
191
- vatStatus: SupplierVatStatus;
192
- /** Peppol participant identifier in `scheme:value` form (e.g. `"0208:0793904121"`). */
193
- peppolID?: string | null;
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
- /** Display + legal name shown on the invoice. */
206
- name: string;
207
- /** Customer address, already normalized by the caller. */
208
- address: UblAddress;
209
- /**
210
- * The customer's ISO 3166-1 alpha-2 country, used to resolve VAT/registration
211
- * schemes for identifiers that don't carry a country prefix. Pass the
212
- * customer's *own* country (never the supplier's) so the document is not
213
- * mis-routed; falls back to the address country when omitted.
214
- */
215
- countryCode?: string | null;
216
- /** Peppol participant identifier in `scheme:value` form (e.g. `"0208:0793904121"`). */
217
- peppolID?: string | null;
218
- /** Global Location Number (resolved under EAS `0088`). */
219
- glnNumber?: string | null;
220
- /** Generic tax/registration number (no VAT prefix). */
221
- taxNumber?: string | null;
222
- /** VAT number with country prefix (e.g. `"BE0793904121"`). */
223
- vatNumber?: string | null;
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
- filename: string;
256
- bytes: Uint8Array;
257
- /** Document reference ID (BT-122). Defaults to the filename. */
258
- id?: string;
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
- countryCode: string | null;
285
- companyNumber: string | null;
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
- countryCode: string | null;
294
- companyNumber: string | null;
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
- vatNumber: string | null | undefined;
308
- countryCode?: string | null;
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
- peppolID: string | null;
320
- glnNumber: string | null;
321
- taxNumber: string | null;
322
- vatNumber: string | null;
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
- peppolID?: string | null;
353
- glnNumber?: string | null;
354
- taxNumber?: string | null;
355
- vatNumber?: string | null;
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
- amount: number;
370
- taxability_reason?: string | null;
371
- tax_rate_percentage?: number | null;
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
- taxCategoryId?: string | null;
384
- taxabilityReason: string | null;
385
- rate: number;
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
- taxTotal: UblTaxTotal;
408
- monetaryTotal: UblMonetaryTotal;
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
- name: string;
434
- attrs?: XmlAttrs;
435
- /** Leaf text content. Mutually exclusive with `children`. */
436
- text?: string | number | null;
437
- /** Child elements. Mutually exclusive with `text`. */
438
- children?: XmlElement[];
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"}