@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.
- package/CHANGELOG.md +7 -0
- package/README.md +20 -25
- package/dist/build/index.d.ts +58 -193
- package/dist/build/index.d.ts.map +1 -1
- package/dist/build/index.js +229 -130
- package/dist/build/index.js.map +1 -1
- package/dist/errors-C9YYJ1xR.js +33 -0
- package/dist/errors-C9YYJ1xR.js.map +1 -0
- package/dist/index.d.ts +2 -224
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +78 -55
- package/dist/index.js.map +1 -1
- package/dist/types-DossV2at.d.ts +389 -0
- package/dist/types-DossV2at.d.ts.map +1 -0
- package/package.json +1 -1
- package/src/build/address.ts +9 -10
- package/src/build/attachment.ts +13 -9
- package/src/build/identifiers.ts +28 -28
- package/src/build/index.ts +19 -9
- package/src/build/numeric.ts +17 -11
- package/src/build/party.ts +16 -14
- package/src/build/tax-category.ts +5 -4
- package/src/build/tax-totals.ts +31 -20
- package/src/build/ubl/serialize.ts +281 -102
- package/src/build/utils.ts +12 -4
- package/src/errors.ts +16 -0
- package/src/index.ts +5 -1
- package/src/normalize.ts +18 -17
- package/src/parser.ts +85 -30
- package/src/types.ts +187 -23
- package/src/build/ubl/types.ts +0 -179
package/src/build/index.ts
CHANGED
|
@@ -1,26 +1,36 @@
|
|
|
1
|
-
// Generic Peppol BIS Billing 3.0 UBL build core: a
|
|
2
|
-
//
|
|
3
|
-
//
|
|
4
|
-
//
|
|
5
|
-
//
|
|
1
|
+
// Generic Peppol BIS Billing 3.0 UBL build core: a serializer and the
|
|
2
|
+
// party/tax/identifier/attachment builders shared by every "X → UBL" adapter
|
|
3
|
+
// (e.g. @financica/stripe-ubl, and app-specific row builders). The document
|
|
4
|
+
// model is the one the parser produces (`../types`), re-exported here so a
|
|
5
|
+
// build-side caller needs only this subpath.
|
|
6
6
|
|
|
7
7
|
// ── UBL document model + serializer ────────────────────────────────────
|
|
8
8
|
export * from "./ubl/constants";
|
|
9
|
-
export {
|
|
9
|
+
export { UblBuildError } from "../errors";
|
|
10
|
+
export { serializeUblDocument, serializeUblInvoice } from "./ubl/serialize";
|
|
10
11
|
export type {
|
|
11
12
|
UblAddress,
|
|
12
13
|
UblAttachment,
|
|
14
|
+
UblBillingReference,
|
|
13
15
|
UblCompanyId,
|
|
14
|
-
UblDocument,
|
|
15
16
|
UblEndpoint,
|
|
17
|
+
UblInvoice,
|
|
18
|
+
UblInvoicePeriod,
|
|
16
19
|
UblLine,
|
|
17
20
|
UblMonetaryTotal,
|
|
18
21
|
UblParty,
|
|
19
|
-
UblPeriod,
|
|
20
22
|
UblTaxCategory,
|
|
21
23
|
UblTaxSubtotal,
|
|
22
24
|
UblTaxTotal,
|
|
23
|
-
} from "
|
|
25
|
+
} from "../types";
|
|
26
|
+
import type {
|
|
27
|
+
UblInvoice as _UblInvoice,
|
|
28
|
+
UblInvoicePeriod as _UblInvoicePeriod,
|
|
29
|
+
} from "../types";
|
|
30
|
+
/** @deprecated The build and parse models are one; use {@link UblInvoice}. */
|
|
31
|
+
export type UblDocument = _UblInvoice;
|
|
32
|
+
/** @deprecated Use {@link UblInvoicePeriod}. */
|
|
33
|
+
export type UblPeriod = _UblInvoicePeriod;
|
|
24
34
|
|
|
25
35
|
// ── Party builders ─────────────────────────────────────────────────────
|
|
26
36
|
export {
|
package/src/build/numeric.ts
CHANGED
|
@@ -5,11 +5,15 @@ export const roundCurrency = (value: number) =>
|
|
|
5
5
|
/** Convert an integer cent amount into a 2-decimal currency value. */
|
|
6
6
|
export const centsToDecimal = (cents: number) => roundCurrency(cents / 100);
|
|
7
7
|
|
|
8
|
-
/** The `cac:Price` pair for a line:
|
|
8
|
+
/** The `cac:Price` pair for a line: the per-unit price and the optional BT-149. */
|
|
9
9
|
export interface UnitPrice {
|
|
10
|
-
/** `
|
|
11
|
-
|
|
12
|
-
/**
|
|
10
|
+
/** Net price of one unit (`UblLine.unitPrice`). */
|
|
11
|
+
unitPrice: number;
|
|
12
|
+
/**
|
|
13
|
+
* `cbc:BaseQuantity` (BT-149) — set when the per-unit price is not exact in
|
|
14
|
+
* cents; the serializer then emits `PriceAmount = unitPrice × baseQuantity`
|
|
15
|
+
* (the line net). Omitted = 1.
|
|
16
|
+
*/
|
|
13
17
|
baseQuantity?: number | undefined;
|
|
14
18
|
}
|
|
15
19
|
|
|
@@ -17,17 +21,19 @@ export interface UnitPrice {
|
|
|
17
21
|
* Derive the `cac:Price` for a line whose net total is authoritative.
|
|
18
22
|
*
|
|
19
23
|
* Peppol rule PEPPOL-EN16931-R120 checks
|
|
20
|
-
* `quantity × (
|
|
24
|
+
* `quantity × (PriceAmount ÷ BaseQuantity)` against the line net amount within
|
|
21
25
|
* a 0.02 tolerance. Naively rounding `net ÷ quantity` to cents breaks that
|
|
22
26
|
* whenever the division doesn't land on a cent: 940.00 over 14 units gives
|
|
23
27
|
* 67.142857…, which rounds to 67.14, and 14 × 67.14 = 939.96 — off by 0.04 and
|
|
24
28
|
* rejected as a fatal validation error.
|
|
25
29
|
*
|
|
26
30
|
* So the cent-rounded unit price is only used when it reproduces the net
|
|
27
|
-
* exactly. Otherwise the line is priced as a whole via BT-149
|
|
28
|
-
* the net
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
+
* exactly. Otherwise the line is priced as a whole via BT-149: `unitPrice` is
|
|
32
|
+
* the exact (unrounded) `net ÷ quantity` and `baseQuantity` = the quantity, so
|
|
33
|
+
* the serializer writes `PriceAmount` = the net and `BaseQuantity` = the
|
|
34
|
+
* quantity, which is exact at any magnitude instead of merely within tolerance
|
|
35
|
+
* — the residual of a rounded unit price grows with quantity and would
|
|
36
|
+
* eventually breach 0.02 at any fixed precision.
|
|
31
37
|
*/
|
|
32
38
|
export const deriveUnitPrice = (netTotal: number, quantity: number): UnitPrice => {
|
|
33
39
|
// A zero or fractional-to-zero quantity still has to price something; BT-149
|
|
@@ -35,7 +41,7 @@ export const deriveUnitPrice = (netTotal: number, quantity: number): UnitPrice =
|
|
|
35
41
|
const units = quantity > 0 ? quantity : 1;
|
|
36
42
|
const perUnit = roundCurrency(netTotal / units);
|
|
37
43
|
if (roundCurrency(perUnit * units) === roundCurrency(netTotal)) {
|
|
38
|
-
return {
|
|
44
|
+
return { unitPrice: perUnit };
|
|
39
45
|
}
|
|
40
|
-
return {
|
|
46
|
+
return { unitPrice: roundCurrency(netTotal) / units, baseQuantity: units };
|
|
41
47
|
};
|
package/src/build/party.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { type AddressInput, normalizeAddress } from "./address";
|
|
2
2
|
import { buildCompanyId, parsePeppolEndpoint, resolveVatEndpoint } from "./identifiers";
|
|
3
|
-
import type { UblAddress, UblEndpoint, UblParty } from "
|
|
4
|
-
import { normalizeString } from "./utils";
|
|
3
|
+
import type { UblAddress, UblEndpoint, UblParty } from "../types";
|
|
4
|
+
import { compact, normalizeString } from "./utils";
|
|
5
5
|
|
|
6
6
|
/**
|
|
7
7
|
* Supplier (seller) VAT status. Drives how zero-VAT lines are reported when the
|
|
@@ -45,20 +45,20 @@ export interface UblSupplier {
|
|
|
45
45
|
peppolID?: string | null;
|
|
46
46
|
}
|
|
47
47
|
|
|
48
|
-
/** Convert a {@link UblSupplier} into the
|
|
48
|
+
/** Convert a {@link UblSupplier} into the seller party (`cac:AccountingSupplierParty`). */
|
|
49
49
|
export const buildSupplierParty = (supplier: UblSupplier): UblParty => {
|
|
50
50
|
const address = normalizeAddress(supplier.address, supplier.countryCode);
|
|
51
|
-
return {
|
|
51
|
+
return compact({
|
|
52
52
|
endpoint: parsePeppolEndpoint(supplier.peppolID),
|
|
53
53
|
name: supplier.name,
|
|
54
|
+
registrationName: supplier.name,
|
|
54
55
|
address,
|
|
55
|
-
|
|
56
|
-
legalName: supplier.name,
|
|
56
|
+
vatId: normalizeString(supplier.vatNumber),
|
|
57
57
|
companyId: buildCompanyId({
|
|
58
58
|
countryCode: supplier.countryCode,
|
|
59
59
|
companyNumber: supplier.companyNumber ?? null,
|
|
60
60
|
}),
|
|
61
|
-
};
|
|
61
|
+
});
|
|
62
62
|
};
|
|
63
63
|
|
|
64
64
|
/**
|
|
@@ -91,7 +91,7 @@ export interface UblCustomer {
|
|
|
91
91
|
}
|
|
92
92
|
|
|
93
93
|
/**
|
|
94
|
-
* Convert a {@link UblCustomer} into the
|
|
94
|
+
* Convert a {@link UblCustomer} into the buyer party (`cac:AccountingCustomerParty`).
|
|
95
95
|
*
|
|
96
96
|
* The Peppol `EndpointID` (BT-49) — which routes the document — is resolved in
|
|
97
97
|
* priority order: an explicit `endpointOverride` (e.g. a confirmed-registered
|
|
@@ -106,22 +106,24 @@ export const buildCustomerParty = (
|
|
|
106
106
|
endpointOverride?: UblEndpoint | null,
|
|
107
107
|
): UblParty => {
|
|
108
108
|
const countryCode =
|
|
109
|
-
normalizeString(customer.countryCode) ?? customer.address.countryCode;
|
|
109
|
+
normalizeString(customer.countryCode) ?? customer.address.countryCode ?? null;
|
|
110
110
|
const endpoint =
|
|
111
111
|
endpointOverride ??
|
|
112
112
|
parsePeppolEndpoint(customer.peppolID) ??
|
|
113
|
-
(customer.glnNumber
|
|
113
|
+
(customer.glnNumber
|
|
114
|
+
? { scheme: "0088", value: customer.glnNumber }
|
|
115
|
+
: undefined) ??
|
|
114
116
|
resolveVatEndpoint({ vatNumber: customer.vatNumber, countryCode });
|
|
115
117
|
|
|
116
|
-
return {
|
|
118
|
+
return compact({
|
|
117
119
|
endpoint,
|
|
118
120
|
name: customer.name,
|
|
121
|
+
registrationName: customer.name,
|
|
119
122
|
address: customer.address,
|
|
120
|
-
|
|
121
|
-
legalName: customer.name,
|
|
123
|
+
vatId: normalizeString(customer.vatNumber),
|
|
122
124
|
companyId: buildCompanyId({
|
|
123
125
|
countryCode,
|
|
124
126
|
companyNumber: customer.taxNumber ?? null,
|
|
125
127
|
}),
|
|
126
|
-
};
|
|
128
|
+
});
|
|
127
129
|
};
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { SupplierVatStatus } from "./party";
|
|
2
|
-
import type { UblLine, UblTaxCategory } from "
|
|
2
|
+
import type { UblLine, UblTaxCategory } from "../types";
|
|
3
3
|
import { normalizeString } from "./utils";
|
|
4
4
|
|
|
5
5
|
/**
|
|
@@ -34,8 +34,8 @@ export interface TaxAmountInfo {
|
|
|
34
34
|
tax_rate_percentage?: number | null;
|
|
35
35
|
}
|
|
36
36
|
|
|
37
|
-
const normalizeTaxCategoryId = (value: string | null | undefined): string |
|
|
38
|
-
normalizeString(value)?.toUpperCase()
|
|
37
|
+
const normalizeTaxCategoryId = (value: string | null | undefined): string | undefined =>
|
|
38
|
+
normalizeString(value)?.toUpperCase();
|
|
39
39
|
|
|
40
40
|
/**
|
|
41
41
|
* Map an explicit UBL category hint, a Stripe `taxability_reason`, and/or a
|
|
@@ -82,7 +82,8 @@ export const taxCategoryFromReasonOrRate = (params: {
|
|
|
82
82
|
id: "E",
|
|
83
83
|
percent: 0,
|
|
84
84
|
exemptionReason:
|
|
85
|
-
(reason ? EXEMPTION_REASON_TEXT[reason] :
|
|
85
|
+
(reason ? EXEMPTION_REASON_TEXT[reason] : undefined) ??
|
|
86
|
+
"Exempt from VAT",
|
|
86
87
|
};
|
|
87
88
|
}
|
|
88
89
|
if (categoryHint === "Z" || reason === "zero_rated" || params.rate <= 0) {
|
package/src/build/tax-totals.ts
CHANGED
|
@@ -1,11 +1,15 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { UblBuildError } from "../errors";
|
|
2
2
|
import type {
|
|
3
3
|
UblLine,
|
|
4
4
|
UblMonetaryTotal,
|
|
5
5
|
UblTaxCategory,
|
|
6
6
|
UblTaxSubtotal,
|
|
7
7
|
UblTaxTotal,
|
|
8
|
-
} from "
|
|
8
|
+
} from "../types";
|
|
9
|
+
import { deriveUnitPrice, roundCurrency } from "./numeric";
|
|
10
|
+
import { compact } from "./utils";
|
|
11
|
+
|
|
12
|
+
const lineNet = (line: UblLine): number => line.lineExtensionAmount ?? 0;
|
|
9
13
|
|
|
10
14
|
/**
|
|
11
15
|
* Adjust the largest line's net amount so the line nets sum to the
|
|
@@ -22,39 +26,38 @@ export const reconcileLinesToExclTotal = (
|
|
|
22
26
|
authoritativeTotalExclVat: number,
|
|
23
27
|
): UblLine[] => {
|
|
24
28
|
if (lines.length === 0) return lines;
|
|
25
|
-
const computed = roundCurrency(
|
|
26
|
-
lines.reduce((sum, line) => sum + line.lineExtensionAmount, 0),
|
|
27
|
-
);
|
|
29
|
+
const computed = roundCurrency(lines.reduce((sum, line) => sum + lineNet(line), 0));
|
|
28
30
|
const diff = roundCurrency(authoritativeTotalExclVat - computed);
|
|
29
31
|
if (diff === 0) return lines;
|
|
30
32
|
|
|
31
33
|
const largestIdx = lines.reduce(
|
|
32
34
|
(maxIdx, line, idx, arr) =>
|
|
33
|
-
line
|
|
34
|
-
? idx
|
|
35
|
-
: maxIdx,
|
|
35
|
+
lineNet(line) > lineNet(arr[maxIdx] ?? line) ? idx : maxIdx,
|
|
36
36
|
0,
|
|
37
37
|
);
|
|
38
38
|
|
|
39
39
|
return lines.map((line, idx) => {
|
|
40
40
|
if (idx !== largestIdx) return line;
|
|
41
|
-
const adjusted = roundCurrency(line
|
|
41
|
+
const adjusted = roundCurrency(lineNet(line) + diff);
|
|
42
42
|
// Re-derive the price from the adjusted net through the shared helper —
|
|
43
43
|
// nudging the net without re-deriving BT-146/BT-149 to match is exactly
|
|
44
44
|
// what PEPPOL-EN16931-R120 rejects. Assign `baseQuantity` unconditionally
|
|
45
45
|
// so a line that no longer needs one doesn't keep a stale value.
|
|
46
|
-
const {
|
|
47
|
-
|
|
46
|
+
const { unitPrice, baseQuantity } = deriveUnitPrice(
|
|
47
|
+
adjusted,
|
|
48
|
+
line.quantity ?? 0,
|
|
49
|
+
);
|
|
50
|
+
return compact({
|
|
48
51
|
...line,
|
|
49
52
|
lineExtensionAmount: adjusted,
|
|
50
|
-
|
|
53
|
+
unitPrice,
|
|
51
54
|
baseQuantity,
|
|
52
|
-
};
|
|
55
|
+
});
|
|
53
56
|
});
|
|
54
57
|
};
|
|
55
58
|
|
|
56
59
|
const categoryKey = (category: UblTaxCategory): string =>
|
|
57
|
-
`${category.id}:${category.percent}`;
|
|
60
|
+
`${category.id ?? ""}:${category.percent ?? ""}`;
|
|
58
61
|
|
|
59
62
|
export interface BuildTaxTotalsResult {
|
|
60
63
|
taxTotal: UblTaxTotal;
|
|
@@ -87,6 +90,9 @@ export interface BuildTaxTotalsOptions {
|
|
|
87
90
|
* invariant holds by construction. The result is *not* clamped: a prepayment
|
|
88
91
|
* exceeding the total yields a negative payable amount, surfacing the upstream
|
|
89
92
|
* overpayment rather than hiding it.
|
|
93
|
+
*
|
|
94
|
+
* @throws {UblBuildError} for a line without a `taxCategory` — there is no
|
|
95
|
+
* VAT breakdown to put it in.
|
|
90
96
|
*/
|
|
91
97
|
export const buildTaxTotals = (
|
|
92
98
|
lines: UblLine[],
|
|
@@ -98,28 +104,33 @@ export const buildTaxTotals = (
|
|
|
98
104
|
>();
|
|
99
105
|
|
|
100
106
|
for (const line of lines) {
|
|
107
|
+
if (!line.taxCategory) {
|
|
108
|
+
throw new UblBuildError(
|
|
109
|
+
`Line ${line.id} has no taxCategory (BT-151); cannot build the VAT breakdown`,
|
|
110
|
+
);
|
|
111
|
+
}
|
|
101
112
|
const key = categoryKey(line.taxCategory);
|
|
102
113
|
const current = groups.get(key) ?? {
|
|
103
114
|
category: line.taxCategory,
|
|
104
115
|
taxableAmount: 0,
|
|
105
116
|
};
|
|
106
|
-
current.taxableAmount = roundCurrency(
|
|
107
|
-
current.taxableAmount + line.lineExtensionAmount,
|
|
108
|
-
);
|
|
117
|
+
current.taxableAmount = roundCurrency(current.taxableAmount + lineNet(line));
|
|
109
118
|
groups.set(key, current);
|
|
110
119
|
}
|
|
111
120
|
|
|
112
121
|
const subtotals: UblTaxSubtotal[] = Array.from(groups.values()).map((group) => ({
|
|
113
122
|
taxableAmount: group.taxableAmount,
|
|
114
|
-
taxAmount: roundCurrency(
|
|
123
|
+
taxAmount: roundCurrency(
|
|
124
|
+
(group.taxableAmount * (group.category.percent ?? 0)) / 100,
|
|
125
|
+
),
|
|
115
126
|
category: group.category,
|
|
116
127
|
}));
|
|
117
128
|
|
|
118
129
|
const lineExtensionAmount = roundCurrency(
|
|
119
|
-
lines.reduce((sum, line) => sum + line
|
|
130
|
+
lines.reduce((sum, line) => sum + lineNet(line), 0),
|
|
120
131
|
);
|
|
121
132
|
const taxAmount = roundCurrency(
|
|
122
|
-
subtotals.reduce((sum, subtotal) => sum + subtotal.taxAmount, 0),
|
|
133
|
+
subtotals.reduce((sum, subtotal) => sum + (subtotal.taxAmount ?? 0), 0),
|
|
123
134
|
);
|
|
124
135
|
const taxInclusiveAmount = roundCurrency(lineExtensionAmount + taxAmount);
|
|
125
136
|
|