shareneus 1.5.91 → 1.5.93

package/dist/shared/table-section/pdf-table.header.js

@@ -73,38 +73,31 @@ function getHeadersBySequence(headers) {
         .map((entry) => entry.header);
 }
 function getRenderableColumns(headerConfig) {
-    const hasTaxPercent = headerConfig.some((header) => header.text === 'Tax %');
-    const hasTaxAmount = headerConfig.some((header) => header.text === 'Tax Amount');
-    const hasTaxGroup = hasTaxPercent && hasTaxAmount;
     const columns = [];
     for (const header of headerConfig) {
-        if (hasTaxGroup && header.text === 'Tax %') {
+        if (isTaxPercentHeader(header)) {
             columns.push({
                 type: 'tax',
                 taxKind: 'rate',
-                taxName: '%',
                 dbField: 'CGST',
                 width: getTaxSubWidth(header.width),
             }, {
                 type: 'tax',
-                taxKind: 'amount',
-                dbField: 'CGST',
-                taxName: 'Amount',
+                taxKind: 'rate',
+                dbField: 'SGST',
                 width: getTaxSubWidth(header.width),
             });
             continue;
         }
-        if (hasTaxGroup && header.text === 'Tax Amount') {
+        if (isTaxAmountHeader(header)) {
             columns.push({
                 type: 'tax',
-                taxKind: 'rate',
-                taxName: '%',
-                dbField: 'SGST',
+                taxKind: 'amount',
+                dbField: 'CGST',
                 width: getTaxSubWidth(header.width),
             }, {
                 type: 'tax',
                 taxKind: 'amount',
-                taxName: 'Amount',
                 dbField: 'SGST',
                 width: getTaxSubWidth(header.width),
             });
@@ -119,9 +112,7 @@ function getRenderableColumns(headerConfig) {
     return columns;
 }
 function buildHeaderRows(headerConfig) {
-    const hasTaxPercent = headerConfig.some((header) => header.text === 'Tax %');
-    const hasTaxAmount = headerConfig.some((header) => header.text === 'Tax Amount');
-    const hasTaxGroup = hasTaxPercent && hasTaxAmount;
+    const hasTaxGroup = headerConfig.some((header) => isTaxPercentHeader(header) || isTaxAmountHeader(header));
     const hasDiscPercent = headerConfig.some((header) => header.text === 'Disc %');
     const hasDiscAmount = headerConfig.some((header) => isDiscountAmountHeader(header.text));
     const hasDiscGroup = hasDiscPercent && hasDiscAmount;
@@ -133,14 +124,14 @@ function buildHeaderRows(headerConfig) {
     const topRow = [];
     const subRow = [];
     for (const header of headerConfig) {
-        if (hasTaxGroup && header.text === 'Tax %') {
-            topRow.push(Object.assign({ text: 'CGST', colSpan: 2, alignment: 'center' }, getHeaderCellStyle()), {});
-            subRow.push(Object.assign({ text: '%', alignment: 'center' }, getHeaderCellStyle()), Object.assign({ text: 'Amt', alignment: 'center' }, getHeaderCellStyle()));
+        if (isTaxPercentHeader(header)) {
+            topRow.push(Object.assign({ text: header.text, colSpan: 2, alignment: 'center' }, getHeaderCellStyle()), {});
+            subRow.push(Object.assign({ text: 'CGST', alignment: 'center' }, getHeaderCellStyle()), Object.assign({ text: 'SGST/UGST', alignment: 'center' }, getHeaderCellStyle()));
             continue;
         }
-        if (hasTaxGroup && header.text === 'Tax Amount') {
-            topRow.push(Object.assign({ text: 'SGST/UGST', colSpan: 2, alignment: 'center' }, getHeaderCellStyle()), {});
-            subRow.push(Object.assign({ text: '%', alignment: 'center' }, getHeaderCellStyle()), Object.assign({ text: 'Amt', alignment: 'center' }, getHeaderCellStyle()));
+        if (isTaxAmountHeader(header)) {
+            topRow.push(Object.assign({ text: header.text, colSpan: 2, alignment: 'center' }, getHeaderCellStyle()), {});
+            subRow.push(Object.assign({ text: 'CGST', alignment: 'center' }, getHeaderCellStyle()), Object.assign({ text: 'SGST/UGST', alignment: 'center' }, getHeaderCellStyle()));
             continue;
         }
         if (hasDiscGroup && header.text === 'Disc %') {
@@ -165,6 +156,18 @@ function getTaxSubWidth(width) {
 function isDiscountAmountHeader(text) {
     return text === 'Disc Amount' || text === 'Adisc Amount';
 }
+function isTaxPercentHeader(header) {
+    return normalizeHeaderText(header === null || header === void 0 ? void 0 : header.text) === 'TAX%';
+}
+function isTaxAmountHeader(header) {
+    return normalizeHeaderText(header === null || header === void 0 ? void 0 : header.text) === 'TAXAMOUNT';
+}
+function normalizeHeaderText(value) {
+    return String(value !== null && value !== void 0 ? value : '')
+        .replace(/\s+/g, '')
+        .trim()
+        .toUpperCase();
+}
 function getHeaderCellStyle() {
     return {
         bold: true,

package/dist/tax/index.d.ts

@@ -4,6 +4,6 @@
  * This is the entry point for all tax-related functionality.
  * Import from "shareneus/tax" in both UI and API code.
  */
-export type { TaxComponentType, CalcMethod, AppliedOn, RoundingMethod, TaxCategory, SupplyType, ResolvedSupplyType, WithholdingType, ResolverType, IRegimeComponent, IRegimeFeatures, IRounding, ITreatment, ITaxRegime, ITaxCodeComponent, ITaxCode, ITaxComponent, ITaxSummaryLine, ITaxSummary, IWithholding, IWithholdingCalcInput, ITaxCalcLineInput, ITaxSummaryInput, IRoundingConfig, ITaxExemption, ITaxAuthority, IExternalProvider, } from "./tax.types";
+export type { TaxComponentType, CalcMethod, AppliedOn, RoundingMethod, TaxCategory, SupplyType, ResolvedSupplyType, WithholdingType, ResolverType, IRegimeComponent, IRegimeFeatures, IRounding, ITreatment, ITaxRegime, ITaxCodeComponent, ITaxCode, ITaxComponent, ITaxSummaryLine, ITaxSummary, IWithholding, IWithholdingCalcInput, IComponentOverride, ITaxCalcLineInput, ITaxSummaryInput, IRoundingConfig, IDocumentTotalsInput, IDocumentTotals, ITaxExemption, ITaxAuthority, IExternalProvider, } from "./tax.types";
 export type { IInclusiveResult } from "./tax-calculator";
-export { calculateLineTax, extractNetFromInclusive, sumTaxComponents, computeTaxSummary, determineSupplyType, findTaxCodeByRateAndSupplyType, calculateWithholding, roundAmount, validateTaxId, validateHSNSACLength, convertFlatToTaxes, } from "./tax-calculator";
+export { calculateLineTax, extractNetFromInclusive, sumTaxComponents, computeTaxSummary, computeDocumentTotals, determineSupplyType, findTaxCodeByRateAndSupplyType, calculateWithholding, roundAmount, validateTaxId, validateHSNSACLength, convertFlatToTaxes, } from "./tax-calculator";

package/dist/tax/index.js

@@ -6,12 +6,13 @@
  * Import from "shareneus/tax" in both UI and API code.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.convertFlatToTaxes = exports.validateHSNSACLength = exports.validateTaxId = exports.roundAmount = exports.calculateWithholding = exports.findTaxCodeByRateAndSupplyType = exports.determineSupplyType = exports.computeTaxSummary = exports.sumTaxComponents = exports.extractNetFromInclusive = exports.calculateLineTax = void 0;
+exports.convertFlatToTaxes = exports.validateHSNSACLength = exports.validateTaxId = exports.roundAmount = exports.calculateWithholding = exports.findTaxCodeByRateAndSupplyType = exports.determineSupplyType = exports.computeDocumentTotals = exports.computeTaxSummary = exports.sumTaxComponents = exports.extractNetFromInclusive = exports.calculateLineTax = void 0;
 var tax_calculator_1 = require("./tax-calculator");
 Object.defineProperty(exports, "calculateLineTax", { enumerable: true, get: function () { return tax_calculator_1.calculateLineTax; } });
 Object.defineProperty(exports, "extractNetFromInclusive", { enumerable: true, get: function () { return tax_calculator_1.extractNetFromInclusive; } });
 Object.defineProperty(exports, "sumTaxComponents", { enumerable: true, get: function () { return tax_calculator_1.sumTaxComponents; } });
 Object.defineProperty(exports, "computeTaxSummary", { enumerable: true, get: function () { return tax_calculator_1.computeTaxSummary; } });
+Object.defineProperty(exports, "computeDocumentTotals", { enumerable: true, get: function () { return tax_calculator_1.computeDocumentTotals; } });
 Object.defineProperty(exports, "determineSupplyType", { enumerable: true, get: function () { return tax_calculator_1.determineSupplyType; } });
 Object.defineProperty(exports, "findTaxCodeByRateAndSupplyType", { enumerable: true, get: function () { return tax_calculator_1.findTaxCodeByRateAndSupplyType; } });
 Object.defineProperty(exports, "calculateWithholding", { enumerable: true, get: function () { return tax_calculator_1.calculateWithholding; } });

package/dist/tax/tax-calculator.d.ts

@@ -14,7 +14,7 @@
  * IMPORTANT: All monetary calculations use Big.js to avoid floating-point
  * precision issues. Never use plain JS arithmetic (* / + -) for money.
  */
-import { ITaxCode, ITaxComponent, ITaxSummary, ITaxCalcLineInput, ITaxSummaryInput, IRoundingConfig, ResolvedSupplyType, IWithholding, IWithholdingCalcInput } from "./tax.types";
+import { ITaxCode, ITaxComponent, ITaxSummary, ITaxCalcLineInput, ITaxSummaryInput, IRoundingConfig, IDocumentTotalsInput, IDocumentTotals, ResolvedSupplyType, IWithholding, IWithholdingCalcInput } from "./tax.types";
 /**
  * Calculates tax for a single line item based on the provided TaxCode.
  *
@@ -105,25 +105,30 @@ export declare function sumTaxComponents(taxes: ITaxComponent[] | undefined | nu
  * This is a PURE FUNCTION — it does not read from database.
  * Caller must derive NetAmt from line item fields and pass it in.
  *
- * Groups tax amounts by component Code, then provides totals.
- * TaxableAmt per code = sum of line NetAmt for lines that have that code.
+ * Groups tax amounts by Code+Rate (e.g., CGST@9 and CGST@14 are separate buckets).
+ * TaxableAmt per bucket = sum of line NetAmt for lines that have that Code+Rate.
  * TotalTaxable = sum of unique line NetAmts (not double-counted across components).
  *
- * @param input - All line items with Taxes[] and NetAmt (taxable value), plus regime code
- * @returns ITaxSummary — the aggregated summary (computed, not stored)
+ * Rounding behavior (via input.Rounding):
+ *   - TaxComponentTotal ON: each bucket's Amt is rounded to Precision
+ *   - Otherwise: Amts are at currency precision (from calculateLineTax)
+ *
+ * @param input - All line items with Taxes[] and NetAmt, plus regime code and optional rounding
+ * @returns ITaxSummary — the aggregated summary (stored on the document)
  *
  * @example
  * const summary = computeTaxSummary({
  *     Lines: invoice.Items.map(item => ({
  *         Taxes: item.Taxes,
- *         NetAmt: item.NetAmt,   // Caller derives this from Qty × UnitPrice - Discount
+ *         NetAmt: item.UnAmt - item.Disc - item.RecDisc,
  *     })),
- *     RegimeCode: "IN_GST"
+ *     RegimeCode: "IN_GST",
+ *     Rounding: { Method: "Round", Precision: 0, TaxComponentTotal: true },
  * });
  * // Returns: {
  * //   Lines: [
- * //     { Code: "CGST", TaxableAmt: 50000, Amt: 4500, Rate: 9 },
- * //     { Code: "SGST", TaxableAmt: 50000, Amt: 4500, Rate: 9 }
+ * //     { Code: "CGST", Rate: 9, TaxableAmt: 50000, Amt: 4500 },
+ * //     { Code: "SGST", Rate: 9, TaxableAmt: 50000, Amt: 4500 }
  * //   ],
  * //   TotalTaxable: 50000,
  * //   TotalTax: 9000,
@@ -131,6 +136,50 @@ export declare function sumTaxComponents(taxes: ITaxComponent[] | undefined | nu
  * // }
  */
 export declare function computeTaxSummary(input: ITaxSummaryInput): ITaxSummary;
+/**
+ * Computes all document-level totals in one call: SubTotal, TaxTotal,
+ * TaxSummary, Round, and Total.
+ *
+ * This is the primary function UI/API should call at save time to produce
+ * the stored financial fields. All rounding is applied per the RoundingConfig.
+ *
+ * Flow:
+ *   1. SubTotal = sum of line NetAmts
+ *   2. TaxSummary = grouped by Code+Rate (rounded per TaxComponentTotal)
+ *   3. TaxTotal = sum of TaxSummary Amts
+ *   4. GrandTotal = SubTotal + TaxTotal
+ *   5. If DocTotal ON: round GrandTotal, compute Round adjustment
+ *   6. Total = GrandTotal + Round
+ *
+ * NOTE: Document-level Discount, Adjust, and Withholding are NOT handled here.
+ * The caller applies those after this function returns:
+ *   FinalPayable = Total + Adjust - Withholding.Amt
+ *
+ * @param input - Line items with NetAmt and Taxes[], plus RoundingConfig
+ * @returns IDocumentTotals — all stored financial fields
+ *
+ * @example
+ * // India GST invoice with 2 lines
+ * const totals = computeDocumentTotals({
+ *     Lines: [
+ *         { NetAmt: 5000, Taxes: [{ Code: "CGST", Rate: 9, Amt: 450, TaxCodeId: 1 },
+ *                                  { Code: "SGST", Rate: 9, Amt: 450, TaxCodeId: 1 }] },
+ *         { NetAmt: 3000, Taxes: [{ Code: "CGST", Rate: 9, Amt: 270, TaxCodeId: 1 },
+ *                                  { Code: "SGST", Rate: 9, Amt: 270, TaxCodeId: 1 }] },
+ *     ],
+ *     Rounding: { Method: "Round", Precision: 0, TaxComponentTotal: true, DocTotal: true },
+ *     RegimeCode: "IN_GST",
+ * });
+ * // Returns: {
+ * //   SubTotal: 8000, TaxTotal: 1440, Round: 0, Total: 9440,
+ * //   GrandTotal: 9440,
+ * //   TaxSummary: [
+ * //     { Code: "CGST", Rate: 9, TaxableAmt: 8000, Amt: 720 },
+ * //     { Code: "SGST", Rate: 9, TaxableAmt: 8000, Amt: 720 },
+ * //   ]
+ * // }
+ */
+export declare function computeDocumentTotals(input: IDocumentTotalsInput): IDocumentTotals;
 /**
  * Determines Intra-State or Inter-State based on seller and buyer state codes.
  *

package/dist/tax/tax-calculator.js

@@ -23,6 +23,7 @@ exports.calculateLineTax = calculateLineTax;
 exports.extractNetFromInclusive = extractNetFromInclusive;
 exports.sumTaxComponents = sumTaxComponents;
 exports.computeTaxSummary = computeTaxSummary;
+exports.computeDocumentTotals = computeDocumentTotals;
 exports.determineSupplyType = determineSupplyType;
 exports.findTaxCodeByRateAndSupplyType = findTaxCodeByRateAndSupplyType;
 exports.roundAmount = roundAmount;
@@ -71,13 +72,21 @@ const math_operations_1 = require("../shared/math-operations");
  * // ]
  */
 function calculateLineTax(input, rounding = { Method: "Round", Precision: 2 }) {
-    const { TaxCode, RCM } = input;
+    const { TaxCode, RCM, ComponentOverrides } = input;
     const netAmt = (0, util_1.GetNumber)(input.NetAmt);
     const qty = (0, util_1.GetNumber)(input.Qty, 1);
     // Exempt / Nil / NonTaxable — no components
     if (!TaxCode.Components || TaxCode.Components.length === 0) {
         return [];
     }
+    // Determine line-level rounding precision:
+    // If LineTax is active, apply the configured rounding (Method + Precision)
+    // Otherwise, use standard currency precision (2 decimals, half-up)
+    // This distinction matters when Precision is 0 (India/Japan) — we don't want
+    // to round each line's tax to whole rupees unless LineTax is explicitly ON.
+    const lineRounding = rounding.LineTax
+        ? { Method: rounding.Method, Precision: rounding.Precision }
+        : { Method: "Round", Precision: 2 };
     const result = [];
     // First pass: calculate all "Tax" type components (primary taxes)
     // These are needed because some components (Cess with AppliedOn: "PostTax")
@@ -85,30 +94,55 @@ function calculateLineTax(input, rounding = { Method: "Round", Precision: 2 }) {
     let primaryTaxTotal = 0;
     for (const comp of TaxCode.Components) {
         if (comp.AppliedOn !== "PostTax") {
-            const calculated = calculateSingleComponent(comp, netAmt, qty, rounding);
+            // Apply ComponentOverrides if provided (e.g., CESS Rate/PerUnitAmt from item master)
+            const effectiveComp = applyComponentOverride(comp, ComponentOverrides);
+            const calculated = calculateSingleComponent(effectiveComp, netAmt, qty, lineRounding);
             if (comp.Type === "Tax") {
                 primaryTaxTotal = (0, math_operations_1.Add)(primaryTaxTotal, calculated.Amt);
             }
-            result.push(buildTaxComponent(comp, calculated.Amt, TaxCode._id));
+            result.push(buildTaxComponent(effectiveComp, calculated.Amt, TaxCode._id));
         }
     }
     // Second pass: calculate components that apply on PostTax (tax-on-tax)
     for (const comp of TaxCode.Components) {
         if (comp.AppliedOn === "PostTax") {
+            const effectiveComp = applyComponentOverride(comp, ComponentOverrides);
             const postTaxBase = (0, math_operations_1.Add)(netAmt, primaryTaxTotal);
-            const calculated = calculateSingleComponent(comp, postTaxBase, qty, rounding);
-            result.push(buildTaxComponent(comp, calculated.Amt, TaxCode._id));
+            const calculated = calculateSingleComponent(effectiveComp, postTaxBase, qty, lineRounding);
+            result.push(buildTaxComponent(effectiveComp, calculated.Amt, TaxCode._id));
         }
     }
     return result;
 }
+/**
+ * Merges ComponentOverrides into a TaxCode component.
+ *
+ * Only Rate and PerUnitAmt can be overridden — structural fields (Code, Name,
+ * Type, CalcMethod, AppliedOn) always come from the TaxCode definition.
+ *
+ * Primary use case: CESS components where the TaxCode has placeholder values
+ * (Rate: 0, PerUnitAmt: 0) and the actual values come from the item master.
+ */
+function applyComponentOverride(comp, overrides) {
+    var _a, _b, _c;
+    if (!overrides)
+        return comp;
+    const override = overrides[comp.Code];
+    if (!override)
+        return comp;
+    return Object.assign(Object.assign({}, comp), { Rate: (_a = override.Rate) !== null && _a !== void 0 ? _a : comp.Rate, PerUnitAmt: (_b = override.PerUnitAmt) !== null && _b !== void 0 ? _b : comp.PerUnitAmt, Unit: (_c = override.Unit) !== null && _c !== void 0 ? _c : comp.Unit });
+}
 /**
  * Calculates tax amount for a single component.
  *
- * Handles three calculation methods:
+ * Handles four calculation methods:
  * - Percent: (netAmt * rate) / 100
  * - PerUnit: perUnitAmt * qty
  * - PerUnitPlusPercent: (perUnitAmt * qty) + (netAmt * rate / 100)
+ * - MaxOfPercentOrPerUnit: max(netAmt * rate / 100, perUnitAmt * qty)
+ *
+ * MaxOfPercentOrPerUnit is used for India CESS on tobacco categories where
+ * the cess is "X% or ₹Y per unit, whichever is higher" (CBIC notification).
  */
 function calculateSingleComponent(comp, baseAmt, qty, rounding) {
     const method = comp.CalcMethod || "Percent";
@@ -139,6 +173,14 @@ function calculateSingleComponent(comp, baseAmt, qty, rounding) {
             amt = (0, math_operations_1.Add)(fixedPart, percentPart);
             break;
         }
+        case "MaxOfPercentOrPerUnit": {
+            const perUnitAmt = (0, util_1.GetNumber)(comp.PerUnitAmt);
+            const rate = (0, util_1.GetNumber)(comp.Rate);
+            const perUnitResult = (0, math_operations_1.Multiply)(perUnitAmt, qty);
+            const percentResult = (0, math_operations_1.Multiply)(baseAmt, (0, math_operations_1.Divide)(rate, 100));
+            amt = Math.max(perUnitResult, percentResult);
+            break;
+        }
     }
     // Apply rounding
     amt = roundAmount(amt, rounding);
@@ -146,18 +188,39 @@ function calculateSingleComponent(comp, baseAmt, qty, rounding) {
 }
 /**
  * Builds a lean ITaxComponent snapshot from a component definition and calculated amount.
- * Only stores Code, Rate, Amt, TaxCodeId (4 fields).
+ *
+ * Core fields (always stored): Code, Rate, Amt, TaxCodeId
+ * Snapshot fields (only for non-percent): CalcMethod, PerUnitAmt
+ *
+ * For standard percent-based components (CGST, SGST, IGST), CalcMethod and PerUnitAmt
+ * are omitted to keep the snapshot lean. They're only included when the calculation
+ * method is PerUnit, PerUnitPlusPercent, or MaxOfPercentOrPerUnit — because these
+ * values may come from ComponentOverrides (item CessConfig) and must be preserved
+ * for invoice reprinting, credit notes, and audit.
  *
  * TaxableAmt is NOT stored — it's derivable from line item fields (Qty × UnitPrice - Discount).
  * TaxAmt (sum of Taxes[].Amt) is NOT stored — it's a simple addition, computed on the fly.
  */
 function buildTaxComponent(comp, amt, taxCodeId) {
-    return {
+    const result = {
         Code: comp.Code,
         Rate: comp.Rate,
         Amt: amt,
         TaxCodeId: taxCodeId,
     };
+    // Snapshot CalcMethod, PerUnitAmt, and Unit for non-percent components
+    // so the invoice is self-contained even if item cess config changes later
+    const method = comp.CalcMethod || "Percent";
+    if (method !== "Percent") {
+        result.CalcMethod = method;
+        if (comp.PerUnitAmt != null && comp.PerUnitAmt !== 0) {
+            result.PerUnitAmt = comp.PerUnitAmt;
+        }
+        if (comp.Unit) {
+            result.Unit = comp.Unit;
+        }
+    }
+    return result;
 }
 function extractNetFromInclusive(inclusivePrice, taxCode, qty = 1, rounding = { Method: "Round", Precision: 2 }) {
     if (!taxCode.Components || taxCode.Components.length === 0) {
@@ -170,6 +233,10 @@ function extractNetFromInclusive(inclusivePrice, taxCode, qty = 1, rounding = {
             warning = "Inclusive back-calc is approximate: PerUnitPlusPercent component present";
             break;
         }
+        if (comp.CalcMethod === "MaxOfPercentOrPerUnit") {
+            warning = "Inclusive back-calc is approximate: MaxOfPercentOrPerUnit component present";
+            break;
+        }
         if (comp.AppliedOn === "PostTax") {
             warning = "Inclusive back-calc is approximate: PostTax (tax-on-tax) component present";
             break;
@@ -233,25 +300,30 @@ function sumTaxComponents(taxes) {
  * This is a PURE FUNCTION — it does not read from database.
  * Caller must derive NetAmt from line item fields and pass it in.
  *
- * Groups tax amounts by component Code, then provides totals.
- * TaxableAmt per code = sum of line NetAmt for lines that have that code.
+ * Groups tax amounts by Code+Rate (e.g., CGST@9 and CGST@14 are separate buckets).
+ * TaxableAmt per bucket = sum of line NetAmt for lines that have that Code+Rate.
  * TotalTaxable = sum of unique line NetAmts (not double-counted across components).
  *
- * @param input - All line items with Taxes[] and NetAmt (taxable value), plus regime code
- * @returns ITaxSummary — the aggregated summary (computed, not stored)
+ * Rounding behavior (via input.Rounding):
+ *   - TaxComponentTotal ON: each bucket's Amt is rounded to Precision
+ *   - Otherwise: Amts are at currency precision (from calculateLineTax)
+ *
+ * @param input - All line items with Taxes[] and NetAmt, plus regime code and optional rounding
+ * @returns ITaxSummary — the aggregated summary (stored on the document)
  *
  * @example
  * const summary = computeTaxSummary({
  *     Lines: invoice.Items.map(item => ({
  *         Taxes: item.Taxes,
- *         NetAmt: item.NetAmt,   // Caller derives this from Qty × UnitPrice - Discount
+ *         NetAmt: item.UnAmt - item.Disc - item.RecDisc,
  *     })),
- *     RegimeCode: "IN_GST"
+ *     RegimeCode: "IN_GST",
+ *     Rounding: { Method: "Round", Precision: 0, TaxComponentTotal: true },
  * });
  * // Returns: {
  * //   Lines: [
- * //     { Code: "CGST", TaxableAmt: 50000, Amt: 4500, Rate: 9 },
- * //     { Code: "SGST", TaxableAmt: 50000, Amt: 4500, Rate: 9 }
+ * //     { Code: "CGST", Rate: 9, TaxableAmt: 50000, Amt: 4500 },
+ * //     { Code: "SGST", Rate: 9, TaxableAmt: 50000, Amt: 4500 }
  * //   ],
  * //   TotalTaxable: 50000,
  * //   TotalTax: 9000,
@@ -259,50 +331,54 @@ function sumTaxComponents(taxes) {
  * // }
  */
 function computeTaxSummary(input) {
-    const { Lines, RegimeCode } = input;
-    // Group by component Code
+    const { Lines, RegimeCode, Rounding } = input;
+    // Group by Code+Rate (more granular than Code-only for rate-wise reporting)
     const groupMap = new Map();
     let totalTaxable = 0;
-    let totalTax = 0;
     for (const line of Lines) {
         if (!line.Taxes || line.Taxes.length === 0)
             continue;
         const lineNetAmt = (0, util_1.GetNumber)(line.NetAmt);
         // Track this line's taxable amount at document level (once per line, not per component)
         totalTaxable = (0, math_operations_1.Add)(totalTaxable, lineNetAmt);
-        // Track which codes we've already added this line's NetAmt to (avoid double-counting)
-        const codesTrackedForLine = new Set();
+        // Track which Code+Rate buckets we've already added this line's NetAmt to
+        const bucketsTrackedForLine = new Set();
         for (const tax of line.Taxes) {
-            const key = tax.Code;
+            const rate = (0, util_1.GetNumber)(tax.Rate);
+            const key = `${tax.Code}|${rate}`;
             if (!groupMap.has(key)) {
                 groupMap.set(key, {
                     Code: tax.Code,
+                    Rate: rate,
                     TaxableAmt: 0,
                     Amt: 0,
-                    Rates: new Set(),
                 });
             }
             const group = groupMap.get(key);
-            // Add line's NetAmt to this code's TaxableAmt (once per line per code)
-            if (!codesTrackedForLine.has(key)) {
+            // Add line's NetAmt to this bucket's TaxableAmt (once per line per bucket)
+            if (!bucketsTrackedForLine.has(key)) {
                 group.TaxableAmt = (0, math_operations_1.Add)(group.TaxableAmt, lineNetAmt);
-                codesTrackedForLine.add(key);
+                bucketsTrackedForLine.add(key);
             }
             group.Amt = (0, math_operations_1.Add)(group.Amt, (0, util_1.GetNumber)(tax.Amt));
-            group.Rates.add((0, util_1.GetNumber)(tax.Rate));
-            totalTax = (0, math_operations_1.Add)(totalTax, (0, util_1.GetNumber)(tax.Amt));
         }
     }
-    // Build summary lines
+    // Build summary lines, applying TaxComponentTotal rounding if configured
     const summaryLines = [];
+    let totalTax = 0;
     for (const [, group] of groupMap) {
+        let amt = group.Amt;
+        // If TaxComponentTotal rounding is active, round each bucket's Amt
+        if (Rounding === null || Rounding === void 0 ? void 0 : Rounding.TaxComponentTotal) {
+            amt = roundAmount(amt, { Method: Rounding.Method, Precision: Rounding.Precision });
+        }
         summaryLines.push({
             Code: group.Code,
+            Rate: group.Rate,
             TaxableAmt: group.TaxableAmt,
-            Amt: group.Amt,
-            // Rate is only set if uniform across all lines, otherwise undefined
-            Rate: group.Rates.size === 1 ? Array.from(group.Rates)[0] : undefined,
+            Amt: amt,
         });
+        totalTax = (0, math_operations_1.Add)(totalTax, amt);
     }
     return {
         Lines: summaryLines,
@@ -312,6 +388,85 @@ function computeTaxSummary(input) {
     };
 }
 // ============================================================
+// Document Totals — Full document computation
+// ============================================================
+/**
+ * Computes all document-level totals in one call: SubTotal, TaxTotal,
+ * TaxSummary, Round, and Total.
+ *
+ * This is the primary function UI/API should call at save time to produce
+ * the stored financial fields. All rounding is applied per the RoundingConfig.
+ *
+ * Flow:
+ *   1. SubTotal = sum of line NetAmts
+ *   2. TaxSummary = grouped by Code+Rate (rounded per TaxComponentTotal)
+ *   3. TaxTotal = sum of TaxSummary Amts
+ *   4. GrandTotal = SubTotal + TaxTotal
+ *   5. If DocTotal ON: round GrandTotal, compute Round adjustment
+ *   6. Total = GrandTotal + Round
+ *
+ * NOTE: Document-level Discount, Adjust, and Withholding are NOT handled here.
+ * The caller applies those after this function returns:
+ *   FinalPayable = Total + Adjust - Withholding.Amt
+ *
+ * @param input - Line items with NetAmt and Taxes[], plus RoundingConfig
+ * @returns IDocumentTotals — all stored financial fields
+ *
+ * @example
+ * // India GST invoice with 2 lines
+ * const totals = computeDocumentTotals({
+ *     Lines: [
+ *         { NetAmt: 5000, Taxes: [{ Code: "CGST", Rate: 9, Amt: 450, TaxCodeId: 1 },
+ *                                  { Code: "SGST", Rate: 9, Amt: 450, TaxCodeId: 1 }] },
+ *         { NetAmt: 3000, Taxes: [{ Code: "CGST", Rate: 9, Amt: 270, TaxCodeId: 1 },
+ *                                  { Code: "SGST", Rate: 9, Amt: 270, TaxCodeId: 1 }] },
+ *     ],
+ *     Rounding: { Method: "Round", Precision: 0, TaxComponentTotal: true, DocTotal: true },
+ *     RegimeCode: "IN_GST",
+ * });
+ * // Returns: {
+ * //   SubTotal: 8000, TaxTotal: 1440, Round: 0, Total: 9440,
+ * //   GrandTotal: 9440,
+ * //   TaxSummary: [
+ * //     { Code: "CGST", Rate: 9, TaxableAmt: 8000, Amt: 720 },
+ * //     { Code: "SGST", Rate: 9, TaxableAmt: 8000, Amt: 720 },
+ * //   ]
+ * // }
+ */
+function computeDocumentTotals(input) {
+    const { Lines, Rounding, RegimeCode } = input;
+    // 1. SubTotal = sum of line NetAmts
+    let subTotal = 0;
+    for (const line of Lines) {
+        subTotal = (0, math_operations_1.Add)(subTotal, (0, util_1.GetNumber)(line.NetAmt));
+    }
+    // 2. TaxSummary (handles TaxComponentTotal rounding internally)
+    const taxSummary = computeTaxSummary({
+        Lines,
+        RegimeCode,
+        Rounding,
+    });
+    // 3. TaxTotal from the (potentially rounded) summary
+    const taxTotal = taxSummary.TotalTax;
+    // 4. GrandTotal before doc-level rounding
+    const grandTotal = (0, math_operations_1.Add)(subTotal, taxTotal);
+    // 5. DocTotal rounding
+    let roundedTotal = grandTotal;
+    let roundAdj = 0;
+    if (Rounding.DocTotal !== false) { // default true
+        roundedTotal = roundAmount(grandTotal, { Method: Rounding.Method, Precision: Rounding.Precision });
+        roundAdj = (0, math_operations_1.Subtract)(roundedTotal, grandTotal);
+    }
+    return {
+        SubTotal: subTotal,
+        TaxTotal: taxTotal,
+        TaxSummary: taxSummary.Lines,
+        GrandTotal: grandTotal,
+        Round: roundAdj,
+        Total: roundedTotal,
+    };
+}
+// ============================================================
 // Supply Type Detection
 // ============================================================
 /**

package/dist/tax/tax.types.d.ts

@@ -10,7 +10,7 @@
 /** Tax component types — what kind of tax is this? */
 export type TaxComponentType = "Tax" | "Cess" | "Levy" | "Excise" | "Surcharge" | "Duty";
 /** How the tax is calculated */
-export type CalcMethod = "Percent" | "PerUnit" | "PerUnitPlusPercent";
+export type CalcMethod = "Percent" | "PerUnit" | "PerUnitPlusPercent" | "MaxOfPercentOrPerUnit";
 /** What base amount the tax applies to */
 export type AppliedOn = "NetAmt" | "PostTax" | "Qty";
 /** Rounding methods */
@@ -43,11 +43,23 @@ export interface IRegimeFeatures {
     TaxIdLabel?: string;
     TaxIdFormat?: string;
 }
-/** Rounding rules for a regime */
+/** Rounding rules for a regime.
+ *  Three rounding points control WHERE in the calculation chain rounding is applied.
+ *  LineTax and TaxComponentTotal are mutually exclusive in practice (line-level OR document-level tax rounding).
+ *  DocTotal controls whether the grand total is rounded independently.
+ *
+ *  Country presets:
+ *    India GST:    { Method: "Round", Precision: 0, TaxComponentTotal: true, DocTotal: true }
+ *    US Sales Tax: { Method: "Round", Precision: 2, LineTax: true, DocTotal: true }
+ *    Japan CT:     { Method: "Floor", Precision: 0, TaxComponentTotal: true }
+ *    EU/UK/AU:     { Method: "Round", Precision: 2, DocTotal: true }
+ */
 export interface IRounding {
     Method: RoundingMethod;
     Precision: number;
-    RoundAtLine: boolean;
+    LineTax: boolean;
+    TaxComponentTotal: boolean;
+    DocTotal: boolean;
 }
 /** A registration/treatment type valid for this regime */
 export interface ITreatment {
@@ -80,6 +92,7 @@ export interface ITaxCodeComponent {
     Type: TaxComponentType;
     CalcMethod: CalcMethod;
     PerUnitAmt?: number;
+    Unit?: string;
     AppliedOn: AppliedOn;
 }
 /** The full TaxCode object */
@@ -119,8 +132,10 @@ export interface ITaxCode {
  *   so NOT stored here — line item is the source of truth.
  * - TaxAmt (sum of Taxes[].Amt) is a simple addition → computed on the fly via sumTaxComponents().
  *
- * Full component details (Name, Type, CalcMethod, PerUnitAmt) can be looked up from
- * TaxCode via TaxCodeId when needed.
+ * CalcMethod and PerUnitAmt are optional snapshot fields for non-percent cess.
+ * They capture the resolved calculation parameters at save time so the invoice
+ * remains self-contained and reproducible even if item cess config changes later.
+ * For standard percent-based components (CGST, SGST, IGST), these are omitted.
  *
  * NOTE: ITC is NOT stored here. ITC is at the line-item and document
  * level (purchase-side only).
@@ -130,22 +145,29 @@ export interface ITaxComponent {
     Rate: number;
     Amt: number;
     TaxCodeId?: number;
+    CalcMethod?: CalcMethod;
+    PerUnitAmt?: number;
+    Unit?: string;
 }
 /**
- * TaxSummary is a cached aggregation of line-item Taxes[].
+ * TaxSummary is computed by shareneus at save time and stored on the document.
+ * Line-item Taxes[] remains the source of truth. TaxSummary is a materialized
+ * snapshot for reporting efficiency — avoids complex $unwind/$group in aggregation.
  *
- * NOT required for v1. Line-item Taxes[] is the source of truth.
- * Add TaxSummary later as a performance optimization if GST reports
- * become slow when aggregating from line items.
+ * Grouped by Code+Rate (e.g., CGST@9, CGST@14 are separate entries).
+ * Rounding is applied per the RoundingConfig:
+ *   - If TaxComponentTotal ON: each entry's Amt is rounded to Precision
+ *   - If LineTax ON: Amts are already rounded at line level, summary just sums them
+ *   - Otherwise: Amts are at currency precision (2 decimals)
  */
-/** One line in the TaxSummary (computed on the fly, not stored) */
+/** One line in the TaxSummary — grouped by Code+Rate */
 export interface ITaxSummaryLine {
     Code: string;
+    Rate: number;
     TaxableAmt: number;
     Amt: number;
-    Rate?: number;
 }
-/** Document-level tax summary (computed on the fly, not stored) */
+/** Document-level tax summary — stored on Invoice, Bill, CreditNote, etc. */
 export interface ITaxSummary {
     Lines: ITaxSummaryLine[];
     TotalTaxable: number;
@@ -193,6 +215,24 @@ export interface IWithholdingCalcInput {
     BaseAmt: number;
     PartyLiable?: "Buyer" | "Seller";
 }
+/**
+ * Component-level overrides for tax calculation.
+ *
+ * Keyed by component Code (e.g., "CESS"). When provided, these values
+ * replace the TaxCode component's defaults at calculation time.
+ *
+ * Primary use case: CESS rates are HSN-specific, so the TaxCode defines
+ * the structure (CalcMethod, AppliedOn) while the actual Rate/PerUnitAmt
+ * comes from the item master's CessConfig.
+ *
+ * Only Rate and PerUnitAmt can be overridden — structural fields (Code,
+ * Name, Type, CalcMethod, AppliedOn) always come from the TaxCode.
+ */
+export interface IComponentOverride {
+    Rate?: number;
+    PerUnitAmt?: number;
+    Unit?: string;
+}
 /** Input context for calculating tax on a single line item */
 export interface ITaxCalcLineInput {
     /** Net amount after discounts (taxable value) */
@@ -203,6 +243,21 @@ export interface ITaxCalcLineInput {
     TaxCode: ITaxCode;
     /** Is this a reverse charge line? */
     RCM?: boolean;
+    /**
+     * Optional component-level overrides, keyed by component Code.
+     *
+     * Used when CESS Rate/PerUnitAmt comes from item master (CessConfig)
+     * rather than the TaxCode itself (which has placeholder values like Rate: 0).
+     *
+     * @example
+     * // Item has CessRate: 12 (percent cess from HSN config)
+     * ComponentOverrides: { CESS: { Rate: 12 } }
+     *
+     * @example
+     * // Item has CessPerUnitAmt: 5 (₹5/liter from HSN config)
+     * ComponentOverrides: { CESS: { PerUnitAmt: 5 } }
+     */
+    ComponentOverrides?: Record<string, IComponentOverride>;
 }
 /** Input context for computing document-level TaxSummary.
  *
@@ -218,11 +273,58 @@ export interface ITaxSummaryInput {
     }>;
     /** Tax regime code for the snapshot */
     RegimeCode?: string;
+    /** Rounding config — if provided, applies TaxComponentTotal rounding to summary Amts */
+    Rounding?: IRoundingConfig;
 }
-/** Rounding settings passed to the calculator */
+/**
+ * Rounding settings passed to calculator functions.
+ *
+ * Method + Precision define HOW to round.
+ * LineTax / TaxComponentTotal / DocTotal define WHERE (which rounding points are active).
+ *
+ * When passed to calculateLineTax:
+ *   - LineTax ON → round each Taxes[].Amt to Precision
+ *   - LineTax OFF → round to standard currency precision (2 decimals)
+ *
+ * When passed to computeTaxSummary:
+ *   - TaxComponentTotal ON → round each Code+Rate bucket's Amt to Precision
+ *
+ * When passed to computeDocumentTotals:
+ *   - DocTotal ON → round the grand total to Precision
+ */
 export interface IRoundingConfig {
     Method: RoundingMethod;
     Precision: number;
+    LineTax?: boolean;
+    TaxComponentTotal?: boolean;
+    DocTotal?: boolean;
+}
+/** Input for computing all document-level totals in one call */
+export interface IDocumentTotalsInput {
+    /** All line items — caller derives NetAmt from line item fields (UnAmt - Disc - RecDisc) */
+    Lines: Array<{
+        NetAmt: number;
+        Taxes?: ITaxComponent[];
+    }>;
+    /** Rounding configuration (from TaxRegime.Rounding or Entity Settings) */
+    Rounding: IRoundingConfig;
+    /** Tax regime code for the TaxSummary snapshot */
+    RegimeCode?: string;
+}
+/** Result of full document totals computation */
+export interface IDocumentTotals {
+    /** Sum of all line NetAmts (before tax) */
+    SubTotal: number;
+    /** Total tax amount — sum of rounded component Amts per RoundingConfig */
+    TaxTotal: number;
+    /** Rate-wise tax breakdown — grouped by Code+Rate, rounded per config */
+    TaxSummary: ITaxSummaryLine[];
+    /** SubTotal + TaxTotal (before DocTotal rounding) */
+    GrandTotal: number;
+    /** Rounding adjustment: RoundedTotal - GrandTotal (0 if DocTotal is off) */
+    Round: number;
+    /** Final amount: GrandTotal + Round */
+    Total: number;
 }
 /**
  * Tax exemption reasons — used when a line item or contact is exempt from tax.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shareneus",
-  "version": "1.5.91",
+  "version": "1.5.93",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",