@tallyui/pos 3.2.0 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/pos",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "type": "module",
   "description": "Shared POS business logic for Tally UI — tax, orders, payments, discounts, receipts",
   "main": "./dist/index.js",
@@ -27,20 +27,20 @@
     "directory": "packages/pos"
   },
   "peerDependencies": {
-    "@tallyui/core": "^3.2.0",
+    "@tallyui/core": "^3.3.0",
     "react": ">=18",
     "rxdb": "~17.5.0",
     "rxjs": ">=7"
   },
   "devDependencies": {
-    "@tallyui/core": "3.2.0",
+    "@tallyui/core": "3.3.0",
     "@types/react": ">=18",
     "react": "^19.2.4",
     "rxdb": "17.5.0",
     "rxjs": "7.8.2",
-    "@tallyui/connector-medusa": "3.2.0",
-    "@tallyui/connector-woocommerce": "3.2.0",
-    "@tallyui/database": "3.2.0"
+    "@tallyui/connector-medusa": "3.3.0",
+    "@tallyui/connector-woocommerce": "3.3.0",
+    "@tallyui/database": "3.3.0"
   },
   "scripts": {
     "build": "tsup",

package/src/index.ts

@@ -37,6 +37,10 @@ export type {
   LineItem,
   LineTaxLine,
   AddLineInput,
+  ChargeLine,
+  ChargeInput,
+  FeeLine,
+  ShippingLine,
   Discount,
   AppliedDiscount,
   DisplayTotals,
@@ -64,7 +68,7 @@ export { createRegisterOutbox, useRegisterOutbox } from './outbox';
 export type { RegisterOutboxOptions, RegisterOutbox, UseRegisterOutboxOptions, UseRegisterOutboxResult } from './outbox';
 export { createBackendNotFound } from './outbox/backend-not-found';
 export type { BackendNotFound } from './outbox/backend-not-found';
-export type { HttpTransportOptions, OrderOutboxOptions, OrderOutbox, TransportOutcome, CommandTransport, OutboxState, UseOrderOutboxOptions, UseOrderOutboxResult } from './outbox';
+export type { HttpTransportOptions, OrderOutboxOptions, OrderOutbox, TransportOutcome, CommandTransport, OrderTransportContext, OutboxState, UseOrderOutboxOptions, UseOrderOutboxResult } from './outbox';
 export { tenderReducer, initTenderState, initialTenderState, appliedMinor, changeMinor, quickTenderedAmounts, evenSplitShareMinor, activePlan, planLegs, MAX_TENDER_MINOR } from './tender';
 export type { PaymentTransport, TenderView, TenderLineId, TenderPlan, SplitTab, TenderState, TenderKey, TenderAction, PlanLeg } from './tender';
 

package/src/order/index.ts

@@ -13,6 +13,10 @@ export type {
   LineItem,
   LineTaxLine,
   AddLineInput,
+  ChargeLine,
+  ChargeInput,
+  FeeLine,
+  ShippingLine,
   Discount,
   AppliedDiscount,
   DisplayTotals,

package/src/order/order-builder.ts

@@ -4,6 +4,7 @@ import type { TaxContext } from '../tax/types';
 import { taxMicros, roundMicrosToMinor, roundedTaxByRate } from '../tax/exact';
 import { taxLogger } from '../tax/tax-provider';
 import { allocateOrderDiscount } from './allocate-order-discount';
+import { woocommerceLine, woocommerceTotals } from './woocommerce-tax';
 import type {
   Order,
   LineItem,
@@ -12,6 +13,7 @@ import type {
   Payment,
   CustomerSummary,
   AddLineInput,
+  ChargeInput, ChargeLine, FeeLine, ShippingLine,
 } from './types';
 
 /** Tax contexts already warned that per_rate_group_items fell back to per_order for inclusive lines (#287). */
@@ -27,7 +29,7 @@ function roundHalfAway(n: number): number {
 }
 
 /** The settlement totals of recalculated lines; the display figures derive from them (ADR-063). */
-function sumLines(lines: LineItem[], rounding?: TaxRounding): { subtotalMinor: number; taxMinor: number; totalMinor: number } {
+function sumLines(lines: Pick<LineItem, 'netMinor' | 'taxMicros' | 'taxInclusive' | 'taxLines'>[], rounding?: TaxRounding): { subtotalMinor: number; taxMinor: number; totalMinor: number } {
   // per_line_items, per_rate_group_items (#287): total = Σ rounded nets + tax (order-level-tax-calculation-strategy.js:44-49, order.entity.js:88-89).
   const rounded = roundedTaxByRate(lines, rounding);
   if (rounded) return { subtotalMinor: rounded.baseMinor, taxMinor: rounded.taxMinor, totalMinor: Math.max(0, rounded.baseMinor + rounded.taxMinor) };
@@ -70,6 +72,12 @@ export interface OrderBuilder {
   order$: Observable<Order>;
   addProduct(doc: any, traits: ProductTraits, options?: { variantId?: string; quantity?: number }): string;
   addLine(input: AddLineInput): string;
+  addFee(input: ChargeInput): string;
+  updateFee(id: string, patch: Partial<ChargeInput>): void;
+  removeFee(id: string): void;
+  addShipping(input: ChargeInput & { methodId?: string }): string;
+  updateShipping(id: string, patch: Partial<ChargeInput & { methodId?: string }>): void;
+  removeShipping(id: string): void;
   updateQuantity(lineId: string, quantity: number): void;
   /** Sets a line's unit price (a till price edit), in minor units of the order's currency and the line's own tax mode; its discounts and tax are recomputed. */
   setUnitPrice(lineId: string, amountMinor: number): void;
@@ -89,8 +97,18 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
   const { taxContext } = options;
   const currency = options.currency.toUpperCase();
   const orderId = options.id ?? uid();
+  const woo = taxContext.rounding?.granularity === 'woocommerce' && taxContext.getTaxRates ? taxContext.rounding : undefined;
+  const wooLine = (amount: number, taxClass: string | undefined, inclusive: boolean, untaxed = false, shipping = false) =>
+    woocommerceLine(amount, untaxed ? [] : taxContext.getTaxRates!(taxClass, { shipping }), inclusive, currency, woo!.roundAtSubtotal, taxContext.pricesIncludeTax);
+  const displayAmount = (line: LineItem, amount: number) => {
+    if (!woo || line.taxInclusive === taxContext.pricesIncludeTax) return toDisplayMode(line, amount, taxContext.pricesIncludeTax);
+    const item = wooLine(amount, line.taxClass, line.taxInclusive, line.taxStatus === 'none');
+    return taxContext.pricesIncludeTax ? item.totalMinor : item.netMinor;
+  };
 
   let lineItems: LineItem[] = [];
+  let fees: FeeLine[] = [];
+  let shipping: ShippingLine[] = [];
   let orderDiscounts: AppliedDiscount[] = [];
   let payments: Payment[] = [];
   let customer: CustomerSummary | null = null;
@@ -115,6 +133,8 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     const lineDiscountMinor = Math.min(grossMinor, recalcedDiscounts.reduce((sum, d) => sum + d.amountMinor, 0));
     const discountMinor = lineDiscountMinor + orderDiscountMinor;
     const netMinor = grossMinor - discountMinor;
+    if (woo) return { ...line, discounts: recalcedDiscounts, discountMinor, orderDiscountMinor,
+      ...wooLine(netMinor, line.taxClass, line.taxInclusive, line.taxStatus === 'none') };
     const combinedRate = line.taxLines.reduce((sum, tax) => sum + tax.ratePpm, 0);
     // Tax in the line's own mode, from its own unit price × quantity: never re-tax a rounded base.
     const inclusiveTax = line.taxInclusive ? taxMicros(netMinor, combinedRate, true) : 0n;
@@ -157,7 +177,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     // parity). A fixed discount is computed on what remains, as before. Every discount is then capped at what
     // remains, which decreases as each is applied, and the total is allocated to the lines, which are then
     // taxed on what is left.
-    const lineAmounts = lineItems.map((li) => li.netMinor);
+    const lineAmounts = lineItems.map((li) => woo ? li.unitPriceMinor * li.quantity - li.discountMinor : li.netMinor);
     const base = lineAmounts.reduce((sum, amount) => sum + Math.max(0, amount), 0);
     let remaining = base;
     const recalcedOrderDiscounts = orderDiscounts.map((d) => {
@@ -168,8 +188,13 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     const shares = allocateOrderDiscount(lineAmounts, recalcedOrderDiscounts.reduce((sum, d) => sum + d.amountMinor, 0));
     const lines = lineItems.map((li, index) => recalculateLine(li, shares[index]));
 
-    const { subtotalMinor, taxMinor, totalMinor } = sumLines(lines, taxContext.rounding);
-    if (taxContext.rounding?.granularity === 'per_rate_group_items' && lines.some((li) => li.taxInclusive) && !perRateGroupWarned.has(taxContext)) {
+    const wooTotals = woo ? woocommerceTotals(lines, fees, shipping, currency, woo.roundAtSubtotal, taxContext.pricesIncludeTax) : undefined;
+    const { subtotalMinor } = wooTotals ?? sumLines(lines, taxContext.rounding);
+    const charges = [...fees, ...shipping];
+    const taxedLines = [...lines, ...charges.map((charge) => ({ ...charge, taxInclusive: taxContext.pricesIncludeTax,
+      taxMicros: charge.taxLines.reduce((sum, tax) => sum + BigInt(tax.taxMicros), 0n).toString() }))];
+    const { taxMinor, totalMinor } = wooTotals ?? sumLines(taxedLines, taxContext.rounding);
+    if (taxContext.rounding?.granularity === 'per_rate_group_items' && taxedLines.some((li) => li.taxInclusive) && !perRateGroupWarned.has(taxContext)) {
       perRateGroupWarned.add(taxContext);
       taxLogger.warn('per_rate_group_items with inclusive lines: using per_order figures until the display has a rounding row (#287, #310)');
     }
@@ -185,11 +210,11 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
       // with no rows: its capped "discounts" are the negative gross cancelled, not money off.
       const returned = li.unitPriceMinor < 0;
       const discounts = returned ? [] : li.discounts.map((d) => ({
-        discountId: d.id, ...(d.label !== undefined ? { label: d.label } : {}), amountMinor: toDisplayMode(li, d.amountMinor, taxInclusive),
+        discountId: d.id, ...(d.label !== undefined ? { label: d.label } : {}), amountMinor: displayAmount(li, d.amountMinor),
       }));
-      const shareMinor = toDisplayMode(li, li.orderDiscountMinor, taxInclusive);
-      const remainingMinor = toDisplayMode(li, li.netMinor, taxInclusive);
-      const amountMinor = li.taxInclusive === taxInclusive && !returned ? li.unitPriceMinor * li.quantity
+      const shareMinor = displayAmount(li, li.orderDiscountMinor);
+      const remainingMinor = woo ? taxInclusive ? li.totalMinor! : li.netMinor : toDisplayMode(li, li.netMinor, taxInclusive);
+      const amountMinor = !woo && li.taxInclusive === taxInclusive && !returned ? li.unitPriceMinor * li.quantity
         : discounts.reduce((sum, d) => sum + d.amountMinor, remainingMinor + shareMinor);
       return { line: { lineId: li.id, amountMinor, discounts }, shareMinor, remainingMinor, returned };
     });
@@ -197,8 +222,20 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     const orderDiscountDisplay = figures.reduce((sum, f) => sum + f.shareMinor, 0);
     const displayDiscount = displayLines.reduce(
       (sum, line) => line.discounts.reduce((lineSum, d) => lineSum + d.amountMinor, sum), orderDiscountDisplay);
-    const displaySubtotal = (taxInclusive ? totalMinor : totalMinor - taxMinor) + displayDiscount;
-    const residue = displaySubtotal - displayLines.reduce((sum, line) => sum + line.amountMinor, 0);
+    const chargeRows = (items: ChargeLine[]) => items.map(({ id, name, amountMinor, netMinor, totalMinor }) =>
+      ({ id, name, amountMinor: woo ? taxInclusive ? totalMinor! : netMinor : amountMinor }));
+    const displayFees = chargeRows(fees), displayShipping = chargeRows(shipping);
+    let displaySubtotal = (taxInclusive ? totalMinor : totalMinor - taxMinor) + displayDiscount
+      - [...displayFees, ...displayShipping].reduce((sum, charge) => sum + charge.amountMinor, 0);
+    let residue = displaySubtotal - displayLines.reduce((sum, line) => sum + line.amountMinor, 0);
+    if (woo) {
+      // ADR-076: the last shipping row, else fee, else product takes either sign of residue.
+      const charge = displayShipping.at(-1) ?? displayFees.at(-1);
+      const last = charge ?? displayLines.at(-1);
+      if (last) last.amountMinor += residue;
+      if (charge) displaySubtotal -= residue;
+      residue = displaySubtotal - displayLines.reduce((sum, line) => sum + line.amountMinor, 0);
+    }
     const converted = lines.flatMap((li, index) => li.taxInclusive === taxInclusive ? [] : [index]);
     const conversions = converted.reduce((count, index) => count + [lines[index].netMinor, lines[index].orderDiscountMinor,
       ...lines[index].discounts.map((d) => d.amountMinor)].filter((x) => x !== 0).length, 0);
@@ -221,7 +258,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     if (displayDiscount < 0) throw new Error(`Display discount ${displayDiscount} is negative (ADR-063)`);
     for (const { line, shareMinor, returned } of figures) {
       if (returned && line.discounts.length > 0) throw new Error(`Return line ${line.lineId} shows discount rows (ADR-063)`);
-      if (returned) continue;
+      if (returned || woo) continue;
       const rows = line.discounts.reduce((sum, d) => sum + d.amountMinor, 0);
       if (shareMinor < 0 || line.discounts.some((d) => d.amountMinor < 0) || line.amountMinor < rows + shareMinor) {
         throw new Error(`Display line ${line.lineId} shows ${line.amountMinor}, less than its rows ${rows} and share ${shareMinor} (ADR-063)`);
@@ -230,6 +267,8 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     const display = {
       taxInclusive, subtotalMinor: displaySubtotal, discountMinor: displayDiscount, taxMinor, totalMinor,
       lines: displayLines, orderDiscountMinor: orderDiscountDisplay,
+      ...(fees.length ? { fees: displayFees } : {}),
+      ...(shipping.length ? { shipping: displayShipping } : {}),
     };
     const paidMinor = payments.reduce((sum, p) => sum + p.amountMinor, 0);
     const balanceDueMinor = Math.max(0, totalMinor - paidMinor);
@@ -239,6 +278,8 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
       id: orderId,
       status: 'draft',
       lineItems: lines,
+      ...(fees.length ? { fees: [...fees] } : {}),
+      ...(shipping.length ? { shipping: [...shipping] } : {}),
       discounts: recalcedOrderDiscounts,
       payments: [...payments],
       customer,
@@ -263,6 +304,28 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     subject.next(buildOrder());
   }
 
+  function recalculateCharge(id: string, input: ChargeInput, shipping = false): ChargeLine {
+    if (!Number.isInteger(input.amountMinor)) throw new RangeError('Amount must be integer minor units');
+    if (input.amountMinor < 0) throw new RangeError('Amount must be >= 0');
+    if (!input.name.trim()) throw new RangeError('Name must not be empty');
+    const taxStatus = input.taxStatus ?? 'taxable';
+    if (woo) {
+      const line = wooLine(input.amountMinor, input.taxClass, taxContext.pricesIncludeTax, taxStatus === 'none', shipping);
+      return { id, name: input.name, amountMinor: input.amountMinor, taxClass: input.taxClass, taxStatus,
+        ...line };
+    }
+    const code = taxContext.getTaxRateCode?.(input.taxClass);
+    const line = recalculateLine({
+      id, productId: id, name: input.name, sku: '', unitPriceMinor: input.amountMinor, quantity: 1,
+      taxLines: [{ ...(code !== undefined ? { code } : {}),
+        ratePpm: taxStatus === 'none' ? 0 : taxContext.getTaxRatePpm(input.taxClass), taxMicros: '0' }],
+      discounts: [], discountMinor: 0, orderDiscountMinor: 0, netMinor: 0, taxMicros: '0',
+      taxInclusive: taxContext.pricesIncludeTax,
+    });
+    return { id, name: input.name, amountMinor: input.amountMinor, taxClass: input.taxClass, taxStatus,
+      taxLines: line.taxLines, netMinor: line.netMinor, taxMicros: line.taxMicros };
+  }
+
   function addLine(input: AddLineInput): string {
     const { productId, variantId, unitPrice } = input;
     const quantity = input.quantity ?? 1;
@@ -270,12 +333,15 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     if (!Number.isInteger(unitPrice.amount)) throw new RangeError('Price must be integer minor units');
     if (!Number.isInteger(quantity) || quantity < 1) throw new RangeError('Quantity must be an integer >= 1');
     // A rate from the tax class carries the backend's name for it when one is mapped (#287, #288).
-    const code = input.taxRates ? undefined : taxContext.getTaxRateCode?.(input.taxClass);
-    const taxRates = input.taxRates ?? [{ ...(code !== undefined ? { code } : {}), ratePpm: taxContext.getTaxRatePpm(input.taxClass) }];
+    const code = woo || input.taxRates ? undefined : taxContext.getTaxRateCode?.(input.taxClass);
+    const taxRates = woo ? wooLine(unitPrice.amount * quantity, input.taxClass, unitPrice.taxInclusive ?? taxContext.pricesIncludeTax, input.taxStatus === 'none').taxLines
+      : input.taxStatus === 'none' ? [{ ...(code !== undefined ? { code } : {}), ratePpm: 0 }]
+      : input.taxRates ?? [{ ...(code !== undefined ? { code } : {}), ratePpm: taxContext.getTaxRatePpm(input.taxClass) }];
     const taxInclusive = unitPrice.taxInclusive ?? taxContext.pricesIncludeTax;
 
     const existing = lineItems.find(
-      (li) => li.productId === productId && li.variantId === variantId && li.taxInclusive === taxInclusive
+      (li) => !input.custom && !li.custom && li.productId === productId && li.variantId === variantId && li.taxInclusive === taxInclusive
+        && (!woo || li.taxClass === input.taxClass && (li.taxStatus === 'none') === (input.taxStatus === 'none'))
         && li.unitPriceMinor === unitPrice.amount && li.taxLines.length === taxRates.length
         && li.taxLines.every((tax, index) => tax.code === taxRates[index].code && tax.ratePpm === taxRates[index].ratePpm),
     );
@@ -291,7 +357,10 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     const lineId = uid();
     const line: LineItem = {
       id: lineId,
+      ...((input.custom ? input.taxClass !== undefined : woo) ? { taxClass: input.taxClass } : {}),
       productId,
+      ...(input.custom ? { custom: true as const } : {}),
+      ...(input.taxStatus === 'none' ? { taxStatus: 'none' as const } : {}),
       variantId,
       name: input.name,
       sku: input.sku ?? '',
@@ -324,6 +393,36 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     order$: subject.asObservable(),
     addLine,
 
+    addFee(input) {
+      const fee = recalculateCharge(uid(), input);
+      fees = [...fees, fee]; emit(); return fee.id;
+    },
+    updateFee(id, patch) {
+      const fee = fees.find((entry) => entry.id === id);
+      if (!fee) throw new Error(`Unknown fee ${id}`);
+      const updated = recalculateCharge(id, { ...fee, ...patch });
+      fees = fees.map((entry) => entry.id === id ? updated : entry); emit();
+    },
+    removeFee(id) {
+      if (!fees.some((entry) => entry.id === id)) throw new Error(`Unknown fee ${id}`);
+      fees = fees.filter((entry) => entry.id !== id); emit();
+    },
+    addShipping(input) {
+      const charge = { ...recalculateCharge(uid(), input, true), methodId: input.methodId };
+      shipping = [...shipping, charge]; emit(); return charge.id;
+    },
+    updateShipping(id, patch) {
+      const charge = shipping.find((entry) => entry.id === id);
+      if (!charge) throw new Error(`Unknown shipping ${id}`);
+      const input = { ...charge, ...patch };
+      const updated = { ...recalculateCharge(id, input, true), methodId: input.methodId };
+      shipping = shipping.map((entry) => entry.id === id ? updated : entry); emit();
+    },
+    removeShipping(id) {
+      if (!shipping.some((entry) => entry.id === id)) throw new Error(`Unknown shipping ${id}`);
+      shipping = shipping.filter((entry) => entry.id !== id); emit();
+    },
+
     addProduct(doc, traits, opts) {
       const productId = traits.getId(doc);
       if (!traits.isSellable(doc)) throw new Error("addProduct: this product isn't sold in this store's channel");
@@ -342,6 +441,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
         unitPrice,
         quantity: opts?.quantity,
         taxClass: traits.getTaxClass?.(doc, opts?.variantId),
+        ...(traits.getTaxStatus?.(doc, opts?.variantId) === 'none' ? { taxStatus: 'none' as const } : {}),
       });
     },
 
@@ -432,6 +532,8 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
 
     clear() {
       lineItems = [];
+      fees = [];
+      shipping = [];
       orderDiscounts = [];
       payments = [];
       customer = null;

package/src/order/order-drafts.ts

@@ -65,6 +65,9 @@ export function restoreOrderDraft(saved: Order, options: { currency: string; tax
   for (const line of saved.lineItems) {
     const lineId = builder.addLine({
       productId: line.productId,
+      custom: line.custom,
+      taxStatus: line.taxStatus,
+      ...(taxContext.rounding?.granularity === 'woocommerce' ? { taxClass: line.taxClass } : {}),
       variantId: line.variantId,
       name: line.name,
       sku: line.sku,
@@ -83,6 +86,9 @@ export function restoreOrderDraft(saved: Order, options: { currency: string; tax
     }
   }
 
+  for (const fee of saved.fees ?? []) builder.addFee(fee);
+  for (const charge of saved.shipping ?? []) builder.addShipping(charge);
+
   // Restore order-level discounts
   for (const discount of saved.discounts) {
     builder.applyOrderDiscount({

package/src/order/types.ts

@@ -4,6 +4,8 @@ export interface Order {
   id: string;
   status: 'draft' | 'parked' | 'saved' | 'completed';
   lineItems: LineItem[];
+  fees?: FeeLine[];
+  shipping?: ShippingLine[];
   discounts: AppliedDiscount[];
   payments: Payment[];
   customer: CustomerSummary | null;
@@ -34,23 +36,31 @@ export type SentOrder = Omit<Order, 'customer'> & { customer: (Omit<CustomerSumm
  */
 export interface DisplayTotals {
   taxInclusive: boolean;      // = order.pricesIncludeTax
-  subtotalMinor: number;      // before discounts: total − tax + discount when exclusive, total + discount when inclusive
+  subtotalMinor: number;      // product lines before discounts, excluding fees and shipping (ADR-075)
   discountMinor: number;      // Σ lines' discount rows + orderDiscountMinor, in the display mode; >= 0
   taxMinor: number;           // = order.taxMinor (added when exclusive, included when inclusive)
   totalMinor: number;         // = order.totalMinor
   lines: DisplayLine[];       // in lineItems order; Σ amountMinor = subtotalMinor
+  fees?: Array<{ id: string; name: string; amountMinor: number }>;
+  shipping?: Array<{ id: string; name: string; amountMinor: number }>;
   orderDiscountMinor: number; // the order discounts as one row, not allocated: Σ each line's share, converted on its own
 }
 
 /** One line in the display mode (ADR-063): before any discount, with its own discounts as sub-rows. */
 export interface DisplayLine {
   lineId: string;
-  amountMinor: number;        // quantity × unit price in the display mode; the last converted line also carries the rounding residue
+  amountMinor: number;        // quantity × unit price, or WooCommerce's line figure; a residue recipient may adjust it
   discounts: { discountId: string; label?: string; amountMinor: number }[]; // this line's own discounts, each converted on its own
 }
 
 export interface LineItem {
   id: string;
+  taxClass?: string;
+  /** WooCommerce's stored net at rounding precision, in integer micro-minor units, and its rounded gross. */
+  netMicros?: string;
+  totalMinor?: number;
+  custom?: true;
+  taxStatus?: 'none';
   productId: string;
   variantId?: string;
   name: string;
@@ -62,15 +72,33 @@ export interface LineItem {
   discounts: AppliedDiscount[];
   discountMinor: number;      // line discounts + orderDiscountMinor, in the line's own mode
   orderDiscountMinor: number; // this line's allocated share of the order discounts (ADR-062)
-  netMinor: number;           // unitPriceMinor × quantity − discountMinor; the taxed base
+  netMinor: number;           // unitPriceMinor × quantity − discountMinor; under WooCommerce, the rounded exclusive net
   taxMicros: string;          // Σ taxLines[].taxMicros, decimal string of a bigint
   taxInclusive: boolean;      // the price's own tax mode; the order's when the price has none
   /** Set only when the price's tax mode differs from the order's; named price mode → order mode. */
   priceTaxModeConverted?: 'inclusive-to-exclusive' | 'exclusive-to-inclusive';
 }
 
+export interface ChargeLine {
+  id: string;
+  netMicros?: string;
+  totalMinor?: number;
+  name: string;
+  amountMinor: number; // integer >= 0, in the order's tax mode (ADR-075)
+  taxClass?: string;
+  taxStatus: 'taxable' | 'none';
+  taxLines: LineItem['taxLines'];
+  netMinor: number;
+  taxMicros: string;
+}
+export interface FeeLine extends ChargeLine {}
+export interface ShippingLine extends ChargeLine { methodId?: string }
+export interface ChargeInput { name: string; amountMinor: number; taxClass?: string; taxStatus?: 'taxable' | 'none' }
+
 export interface LineTaxLine {
   code?: string;
+  rateId?: number;
+  compound?: boolean;
   ratePpm: number;
   taxMicros: string;          // exact, decimal string of a bigint
 }
@@ -113,6 +141,8 @@ export interface PaymentMethod {
 
 export interface AddLineInput {
   productId: string;
+  custom?: true;
+  taxStatus?: 'taxable' | 'none';
   variantId?: string;
   name: string;
   sku?: string;

package/src/order/woocommerce-tax.ts

@@ -0,0 +1,68 @@
+import { minorUnitDigits, woocommerceTax } from '@tallyui/core';
+import type { WooRate } from '../tax/types';
+import type { RateTaxLine } from '../tax/exact';
+import type { ChargeLine, LineItem, LineTaxLine } from './types';
+
+/** ADR-076: all WooCommerce float arithmetic stays here; only integer money leaves this module. */
+export function woocommerceLine(amountMinor: number, rates: readonly WooRate[], inclusive: boolean, currency: string,
+  roundAtSubtotal: boolean, pricesIncludeTax = inclusive) {
+  const dp = minorUnitDigits(currency), factor = 10 ** dp;
+  const precision = woocommerceTax.getRoundingPrecision(dp);
+  const input = { amount: amountMinor / factor, rates: rates.map((rate) => ({ ...rate, order: rate.priority })),
+    amountIncludesTax: inclusive, dp, perRatePrecision: precision };
+  let result = woocommerceTax.calculateTaxes(input);
+  const net = woocommerceTax.roundHalfUp(input.amount - (inclusive ? result.total : 0), precision);
+  // WC_Order_Item_Product::calculate_taxes re-derives from the stored net (#2333 B).
+  if (inclusive && rates.length) result = woocommerceTax.calculateTaxes({ ...input, amount: net, amountIncludesTax: false });
+  const taxLines: LineTaxLine[] = result.taxes.map((tax) => {
+    const rate = rates.find((rate) => rate.id === tax.id)!;
+    return { code: rate.code, rateId: rate.id, compound: rate.compound, ratePpm: Math.round(Number(rate.rate) * 10000),
+      taxMicros: String(Math.round(tax.total * factor * 1e6)) };
+  });
+  const tax = result.taxes.reduce((sum, rate) => sum + (roundAtSubtotal ? rate.total
+    : woocommerceTax.roundTaxTotal(rate.total, dp, pricesIncludeTax)), 0);
+  return { netMinor: Math.round(woocommerceTax.roundHalfUp(net, dp) * factor), netMicros: String(Math.round(net * factor * 1e6)),
+    totalMinor: Math.round(woocommerceTax.roundHalfUp(net + tax, dp) * factor), taxLines,
+    taxMicros: taxLines.reduce((sum, rate) => sum + BigInt(rate.taxMicros), 0n).toString() };
+}
+
+/** calculateOrderTotals: products round conditionally, fees stay raw, shipping always rounds per item. */
+export function woocommerceTotals(lines: readonly LineItem[], fees: readonly ChargeLine[], shipping: readonly ChargeLine[],
+  currency: string, roundAtSubtotal: boolean, inclusive: boolean) {
+  const dp = minorUnitDigits(currency), factor = 10 ** dp;
+  const net = (line: LineItem | ChargeLine) => Number(line.netMicros) / (factor * 1e6);
+  const productNet = lines.reduce((sum, line) => sum + (roundAtSubtotal ? net(line) : woocommerceTax.roundHalfUp(net(line), dp)), 0);
+  const amount = productNet + fees.reduce((sum, line) => sum + net(line), 0)
+    + shipping.reduce((sum, line) => sum + woocommerceTax.roundHalfUp(net(line), dp), 0);
+  const taxes = (items: readonly (LineItem | ChargeLine)[]) => woocommerceTax.roundHalfUp(items.reduce((sum, line) =>
+    line.taxLines.reduce((sum, tax) => sum + (roundAtSubtotal ? Number(tax.taxMicros) / (factor * 1e6)
+      : woocommerceTax.roundTaxTotal(Number(tax.taxMicros) / (factor * 1e6), dp, inclusive)), sum), 0), woocommerceTax.getRoundingPrecision(dp));
+  const tax = woocommerceTax.roundHalfUp(taxes([...lines, ...fees]) + taxes(shipping), 6);
+  return { subtotalMinor: Math.round(woocommerceTax.roundHalfUp(productNet, dp) * factor),
+    taxMinor: Math.round((roundAtSubtotal ? woocommerceTax.roundHalfUp(tax, dp) : woocommerceTax.roundTaxTotal(tax, dp, inclusive)) * factor),
+    totalMinor: Math.round(woocommerceTax.roundHalfUp(woocommerceTax.roundHalfUp(amount + tax, 6), dp) * factor) };
+}
+
+/** Order-math's rate buckets, including zero rows; the last row takes the bounded order tax residue. */
+export function woocommerceTaxByRate(lines: readonly { netMinor: number; taxInclusive: boolean; taxLines: readonly LineTaxLine[] }[],
+  roundAtSubtotal: boolean, taxLabels?: Record<number, string>, orderTaxMinor?: number): RateTaxLine[] {
+  const groups = new Map<string, RateTaxLine & { amount: number; inclusive: boolean }>();
+  for (const line of lines) for (const tax of line.taxLines) {
+    const key = JSON.stringify([tax.rateId, tax.code, tax.ratePpm]);
+    const row = groups.get(key) ?? { code: tax.code, ratePpm: tax.ratePpm, label: taxLabels?.[tax.ratePpm] ?? `Tax ${tax.ratePpm / 10000}%`,
+      netMinor: 0, amountMinor: 0, amount: 0, inclusive: line.taxInclusive };
+    const amount = Number(tax.taxMicros) / 1e6;
+    row.amount += roundAtSubtotal ? amount : woocommerceTax.roundTaxTotal(amount, 0, line.taxInclusive);
+    row.netMinor += line.netMinor;
+    groups.set(key, row);
+  }
+  const rows = [...groups.values()].map(({ amount, inclusive, ...row }) => ({ ...row,
+    amountMinor: woocommerceTax.roundTaxTotal(woocommerceTax.roundHalfUp(amount, 6), 0, inclusive) }));
+  if (orderTaxMinor !== undefined && rows.length) {
+    const residue = orderTaxMinor - rows.reduce((sum, row) => sum + row.amountMinor, 0);
+    const bound = Math.floor(rows.length / 2) + 1;
+    if (Math.abs(residue) > bound) throw new Error(`woocommerce tax by rate: residue ${residue} exceeds its bound ${bound} (ADR-076)`);
+    rows[rows.length - 1].amountMinor += residue;
+  }
+  return rows;
+}

package/src/outbox/index.ts

@@ -6,6 +6,6 @@ export { createRegisterOutbox } from './register-outbox';
 export type { RegisterOutboxOptions, RegisterOutbox } from './register-outbox';
 export { useRegisterOutbox } from './use-register-outbox';
 export type { UseRegisterOutboxOptions, UseRegisterOutboxResult } from './use-register-outbox';
-export type { TransportOutcome, CommandTransport, OutboxState } from './types';
+export type { TransportOutcome, CommandTransport, OrderTransportContext, OutboxState } from './types';
 export { useOrderOutbox, outboxLogger } from './use-order-outbox';
 export type { UseOrderOutboxOptions, UseOrderOutboxResult } from './use-order-outbox';

package/src/outbox/order-outbox.ts

@@ -268,6 +268,7 @@ export function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox {
       const firstSend = orders.some((order) => order.sentVersion === undefined);
       const serverMax = (firstSend && validMax(await Promise.resolve().then(() => options.getMaxOrderCreateVersion?.())
         .catch((cause) => { outboxLogger.warn('Failed to read capabilities', { cause }); }))) || 3;
+      const localOrders = new Map<string, PosOrder>();
       const batch = await Promise.all(orders.map(async (order) => {
         const frozen = freezeSentForm(order);
         const attempt = (attempts.get(order.commandId) ?? 0) + 1;
@@ -276,9 +277,9 @@ export function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox {
         try {
           envelope = toOrderCreateEnvelope(frozen, deviceId, attempt, { maxVersion: order.sentVersion ?? serverMax });
         } catch (cause) {
-          // A discounted order the server can take only at 1 goes as before (at most 3): the refusal rejects it.
+          // Content that cannot downgrade goes at its required version: the server's refusal rejects it.
           if (!(cause instanceof UnsupportedOrderVersionError)) throw cause;
-          envelope = toOrderCreateEnvelope(frozen, deviceId, attempt, { maxVersion: 3 });
+          envelope = toOrderCreateEnvelope(frozen, deviceId, attempt, { maxVersion: cause.needed === 5 ? 5 : 3 });
         }
         // Bounds apply when frozen: persist older tills' sent forms before sending (Front desk, 2026-09-29). A first
         // send's version is stored, awaited, before the batch request leaves, so a crash in between keeps it.
@@ -286,9 +287,10 @@ export function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox {
           await (await collection.findOne(order.id).exec())?.incrementalModify((data) =>
             ({ ...freezeSentForm(data), sentVersion: data.sentVersion ?? envelope.version }));
         }
+        localOrders.set(envelope.id, frozen);
         return envelope;
       }));
-      let outcome = await transport.send(batch);
+      let outcome = await transport.send(batch, { local: { orders: localOrders } });
       // A 404 answers the whole batch (the route is missing); any other answer resets the count. Offline changes nothing.
       backendNotFound.record(outcome, now());
       if (outcome.kind !== 'retry' || outcome.reason !== 'network') {

package/src/outbox/types.ts

@@ -1,4 +1,11 @@
 import type { AnyCommandEnvelope, CommandEnvelope, CommandResult, OrderCreatePayload } from '@tallyui/core';
+import type { PosOrder } from '../pos-order';
+
+/** Local-only context for a transport (ADR-076 amendment 1): never serialised, never part of a payload. */
+export interface OrderTransportContext {
+  /** The stored (frozen) order of each envelope in the batch, keyed by the envelope's `id` (its commandId). */
+  local: { orders: ReadonlyMap<string, PosOrder> };
+}
 
 export type TransportOutcome =
   | { kind: 'results'; results: CommandResult[] }
@@ -9,7 +16,7 @@ export type TransportOutcome =
   | { kind: 'retry'; reason: string; retryAfterMs?: number };
 
 export interface CommandTransport<E extends AnyCommandEnvelope = CommandEnvelope<OrderCreatePayload>> {
-  send(batch: E[]): Promise<TransportOutcome>;
+  send(batch: E[], context?: OrderTransportContext): Promise<TransportOutcome>;
 }
 
 export interface OutboxState {