@financica/ubl 0.17.0 → 0.18.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,5 +1,6 @@
1
1
  import { UblBuildError } from "../errors";
2
2
  import type {
3
+ UblAllowanceCharge,
3
4
  UblLine,
4
5
  UblMonetaryTotal,
5
6
  UblTaxCategory,
@@ -73,6 +74,13 @@ export interface BuildTaxTotalsOptions {
73
74
  prepaidAmount?: number;
74
75
  /** BT-114 — rounding applied to the payable amount. */
75
76
  payableRoundingAmount?: number;
77
+ /**
78
+ * Document-level allowances and charges (BG-20/BG-21). Each one joins the
79
+ * VAT breakdown of its own category (BR-S-08: taxable = line nets −
80
+ * allowances + charges) and feeds BT-107/BT-108, so BT-109 is
81
+ * BT-106 − BT-107 + BT-108 (BR-CO-13). Put the same array on the document.
82
+ */
83
+ allowanceCharges?: UblAllowanceCharge[];
76
84
  }
77
85
 
78
86
  /**
@@ -91,8 +99,8 @@ export interface BuildTaxTotalsOptions {
91
99
  * exceeding the total yields a negative payable amount, surfacing the upstream
92
100
  * overpayment rather than hiding it.
93
101
  *
94
- * @throws {UblBuildError} for a line without a `taxCategory` — there is no
95
- * VAT breakdown to put it in.
102
+ * @throws {UblBuildError} for a line, allowance or charge without a
103
+ * `taxCategory` — there is no VAT breakdown to put it in.
96
104
  */
97
105
  export const buildTaxTotals = (
98
106
  lines: UblLine[],
@@ -117,6 +125,22 @@ export const buildTaxTotals = (
117
125
  current.taxableAmount = roundCurrency(current.taxableAmount + lineNet(line));
118
126
  groups.set(key, current);
119
127
  }
128
+ const allowanceCharges = options?.allowanceCharges ?? [];
129
+ for (const [index, item] of allowanceCharges.entries()) {
130
+ if (!item.taxCategory) {
131
+ throw new UblBuildError(
132
+ `allowanceCharges[${index}] has no taxCategory (BT-95/BT-102); cannot build the VAT breakdown`,
133
+ );
134
+ }
135
+ const key = categoryKey(item.taxCategory);
136
+ const current = groups.get(key) ?? {
137
+ category: item.taxCategory,
138
+ taxableAmount: 0,
139
+ };
140
+ const signed = item.chargeIndicator ? (item.amount ?? 0) : -(item.amount ?? 0);
141
+ current.taxableAmount = roundCurrency(current.taxableAmount + signed);
142
+ groups.set(key, current);
143
+ }
120
144
 
121
145
  const subtotals: UblTaxSubtotal[] = Array.from(groups.values()).map((group) => ({
122
146
  taxableAmount: group.taxableAmount,
@@ -132,7 +156,20 @@ export const buildTaxTotals = (
132
156
  const taxAmount = roundCurrency(
133
157
  subtotals.reduce((sum, subtotal) => sum + (subtotal.taxAmount ?? 0), 0),
134
158
  );
135
- const taxInclusiveAmount = roundCurrency(lineExtensionAmount + taxAmount);
159
+ const allowanceTotalAmount = roundCurrency(
160
+ allowanceCharges
161
+ .filter((item) => !item.chargeIndicator)
162
+ .reduce((sum, item) => sum + (item.amount ?? 0), 0),
163
+ );
164
+ const chargeTotalAmount = roundCurrency(
165
+ allowanceCharges
166
+ .filter((item) => item.chargeIndicator)
167
+ .reduce((sum, item) => sum + (item.amount ?? 0), 0),
168
+ );
169
+ const taxExclusiveAmount = roundCurrency(
170
+ lineExtensionAmount - allowanceTotalAmount + chargeTotalAmount,
171
+ );
172
+ const taxInclusiveAmount = roundCurrency(taxExclusiveAmount + taxAmount);
136
173
 
137
174
  const prepaidAmount = roundCurrency(options?.prepaidAmount ?? 0);
138
175
  const payableRoundingAmount = roundCurrency(options?.payableRoundingAmount ?? 0);
@@ -144,11 +181,70 @@ export const buildTaxTotals = (
144
181
  taxTotal: { taxAmount, subtotals },
145
182
  monetaryTotal: {
146
183
  lineExtensionAmount,
147
- taxExclusiveAmount: lineExtensionAmount,
184
+ taxExclusiveAmount,
148
185
  taxInclusiveAmount,
186
+ ...(allowanceTotalAmount ? { allowanceTotalAmount } : {}),
187
+ ...(chargeTotalAmount ? { chargeTotalAmount } : {}),
149
188
  ...(prepaidAmount ? { prepaidAmount } : {}),
150
189
  ...(payableRoundingAmount ? { payableRoundingAmount } : {}),
151
190
  payableAmount,
152
191
  },
153
192
  };
154
193
  };
194
+
195
+ /**
196
+ * Split one document-level amount into an allowance or charge per VAT
197
+ * category the lines use, pro rata by each category's line nets, so a
198
+ * shipping charge or an invoice-wide discount on a mixed-rate invoice lands in
199
+ * the right VAT subtotals (an ancillary cost follows the supply it belongs to).
200
+ * Cent remainders go to the largest shares so the parts sum to `amount`
201
+ * exactly; categories that receive nothing are omitted. With no positive
202
+ * line net at all the whole amount goes to the first line's category.
203
+ *
204
+ * @throws {UblBuildError} for a line without a `taxCategory`.
205
+ */
206
+ export const allocateAcrossTaxCategories = (
207
+ amount: number,
208
+ lines: UblLine[],
209
+ template: Pick<UblAllowanceCharge, "chargeIndicator" | "reason" | "reasonCode">,
210
+ ): UblAllowanceCharge[] => {
211
+ const groups = new Map<string, { category: UblTaxCategory; net: number }>();
212
+ for (const line of lines) {
213
+ if (!line.taxCategory) {
214
+ throw new UblBuildError(
215
+ `Line ${line.id} has no taxCategory (BT-151); cannot allocate across categories`,
216
+ );
217
+ }
218
+ const key = categoryKey(line.taxCategory);
219
+ const current = groups.get(key) ?? { category: line.taxCategory, net: 0 };
220
+ current.net = roundCurrency(current.net + Math.max(0, lineNet(line)));
221
+ groups.set(key, current);
222
+ }
223
+ const entries = Array.from(groups.values());
224
+ const total = roundCurrency(amount);
225
+ if (entries.length === 0 || total === 0) return [];
226
+ const netSum = entries.reduce((sum, entry) => sum + entry.net, 0);
227
+ const shares =
228
+ netSum > 0
229
+ ? entries.map((entry) => (total * entry.net) / netSum)
230
+ : entries.map((_entry, index) => (index === 0 ? total : 0));
231
+ const cents = shares.map((share) => Math.floor(share * 100 + 1e-9));
232
+ let remainder =
233
+ Math.round(total * 100) - cents.reduce((sum, value) => sum + value, 0);
234
+ const order = shares
235
+ .map((share, index) => ({
236
+ index,
237
+ fraction: share * 100 - Math.floor(share * 100 + 1e-9),
238
+ }))
239
+ .sort((a, b) => b.fraction - a.fraction);
240
+ for (const { index } of order) {
241
+ if (remainder <= 0) break;
242
+ cents[index] = (cents[index] ?? 0) + 1;
243
+ remainder -= 1;
244
+ }
245
+ return entries.flatMap((entry, index) => {
246
+ const value = (cents[index] ?? 0) / 100;
247
+ if (value === 0) return [];
248
+ return [compact({ ...template, amount: value, taxCategory: entry.category })];
249
+ });
250
+ };