@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.
@@ -1,26 +1,36 @@
1
- // Generic Peppol BIS Billing 3.0 UBL build core: a document model, a
2
- // serializer, and the party/tax/identifier/attachment builders shared by every
3
- // "X → UBL" adapter (e.g. @financica/stripe-ubl, and app-specific row builders).
4
- // Exposed under the `@financica/ubl/build` subpath so its build-side types do
5
- // not collide with the parse-side types exported from the package root.
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 { serializeUblDocument } from "./ubl/serialize";
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 "./ubl/types";
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 {
@@ -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: BT-146 and the optional BT-149. */
8
+ /** The `cac:Price` pair for a line: the per-unit price and the optional BT-149. */
9
9
  export interface UnitPrice {
10
- /** `cbc:PriceAmount` (BT-146). */
11
- priceAmount: number;
12
- /** `cbc:BaseQuantity` (BT-149) — the units `priceAmount` covers. Omitted = 1. */
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 × (priceAmount ÷ baseQuantity)` against the line net amount within
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 (`priceAmount` =
28
- * the net, `baseQuantity` = the quantity), which is exact at any magnitude
29
- * instead of merely within tolerance — the residual of a rounded unit price
30
- * grows with quantity and would eventually breach 0.02 at any fixed precision.
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 { priceAmount: perUnit };
44
+ return { unitPrice: perUnit };
39
45
  }
40
- return { priceAmount: roundCurrency(netTotal), baseQuantity: units };
46
+ return { unitPrice: roundCurrency(netTotal) / units, baseQuantity: units };
41
47
  };
@@ -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 "./ubl/types";
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 supplier (seller) party. */
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
- vatNumber: normalizeString(supplier.vatNumber),
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 customer (buyer) party.
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 ? { scheme: "0088", value: customer.glnNumber } : null) ??
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
- vatNumber: normalizeString(customer.vatNumber),
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 "./ubl/types";
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 | null =>
38
- normalizeString(value)?.toUpperCase() ?? null;
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] : null) ?? "Exempt from VAT",
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) {
@@ -1,11 +1,15 @@
1
- import { deriveUnitPrice, roundCurrency } from "./numeric";
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 "./ubl/types";
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.lineExtensionAmount > (arr[maxIdx]?.lineExtensionAmount ?? 0)
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.lineExtensionAmount + diff);
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 { priceAmount, baseQuantity } = deriveUnitPrice(adjusted, line.quantity);
47
- return {
46
+ const { unitPrice, baseQuantity } = deriveUnitPrice(
47
+ adjusted,
48
+ line.quantity ?? 0,
49
+ );
50
+ return compact({
48
51
  ...line,
49
52
  lineExtensionAmount: adjusted,
50
- priceAmount,
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((group.taxableAmount * group.category.percent) / 100),
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.lineExtensionAmount, 0),
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