@tallyui/pos 3.2.0 → 3.3.0

package/src/pos-order/command.ts

@@ -55,9 +55,10 @@ function netDiscountMinor(line: PosOrderLine, pricesIncludeTax: boolean): number
 
 /**
  * The order.create version an order's stored content makes: 3 with ADR-065's figures, else 2 when its lines are
- * discounted (ADR-062), else 1. The builder's, and pos_orders v5's migration's for a row with no `sentVersion`.
+ * discounted (ADR-062), else 1; fees, shipping or custom lines need 5. Also used by pos_orders v5's migration.
  */
-export function contentVersion(order: Pick<PosOrder, 'display' | 'taxByRate' | 'lines'>): 1 | 2 | 3 {
+export function contentVersion(order: Pick<PosOrder, 'display' | 'taxByRate' | 'lines' | 'fees' | 'shipping'>): 1 | 2 | 3 | 5 {
+  if (order.fees?.length || order.shipping?.length || order.lines.some((line) => line.custom)) return 5;
   return order.display && order.taxByRate ? 3 : order.lines.reduce((sum, line) => sum + line.discountMinor, 0) > 0 ? 2 : 1;
 }
 
@@ -73,11 +74,12 @@ export function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attempt
   const grossMinor = order.lines.reduce((sum, line) => sum + line.discountMinor, 0);
   const content = contentVersion(order);
   const cap = options?.maxVersion === undefined ? order.sentVersion : Math.min(options.maxVersion, order.sentVersion ?? options.maxVersion);
+  if (content === 5 && cap !== undefined && cap < 5) throw new UnsupportedOrderVersionError(5, cap);
   if (grossMinor > 0 && cap !== undefined && cap < 2) throw new UnsupportedOrderVersionError(2, cap);
   // Version 4 only when the cap allows it (the server advertises 4, and no sentVersion holds the order lower).
   const version = (content === 3 && cap !== undefined && cap >= 4 ? 4
     : Math.min(content, cap ?? content)) as OrderCreateEnvelope['version'];
-  const lineDiscounts = order.lines.map((line) => version === 4 ? netDiscountMinor(line, order.pricesIncludeTax) : line.discountMinor);
+  const lineDiscounts = order.lines.map((line) => version >= 4 ? netDiscountMinor(line, order.pricesIncludeTax) : line.discountMinor);
   // The order's discount is the sum of its lines', on one basis, so the payload's two always agree.
   const discountMinor = lineDiscounts.reduce((sum, discount) => sum + discount, 0);
   const email = order.customer?.email;
@@ -85,16 +87,26 @@ export function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attempt
   // These are the pre-#222 customerId and sessionId checks, kept byte-exact so stored orders resend older tills' bytes; don't replace with sendable.
   const customerId = typeof id === 'string' && id.length > 0 && id.length <= 64 ? id : undefined;
   const sessionId = order.sessionId ?? order.lateSessionId;
+  const { fees: _fees, shipping: _shipping, ...storedDisplay } = { ...order.display! };
   return {
     id: order.commandId, type: 'order.create', version, createdAt: order.createdAt, deviceId, attempt,
     payload: {
       clientOrderId: order.id, createdAt: order.createdAt, currency: order.currency, pricesIncludeTax: order.pricesIncludeTax,
       lines: order.lines.map((line, i) => ({
-        clientLineId: line.id, variantId: line.variantId ?? line.productId, title: line.name,
+        clientLineId: line.id, ...(line.custom ? { custom: { ...line.custom } } : { variantId: line.variantId ?? line.productId }), title: line.name,
         quantity: line.quantity, unitPriceMinor: line.unitPriceMinor,
         ...(line.taxInclusive !== undefined ? { taxInclusive: line.taxInclusive } : {}),
         ...(lineDiscounts[i] > 0 ? { discountMinor: lineDiscounts[i] } : {}),
       })),
+      ...(version === 5 && order.fees?.length ? { fees: order.fees.map((fee) => ({
+        clientFeeId: fee.id, name: fee.name, amountMinor: fee.amountMinor, taxStatus: fee.taxStatus,
+        ...(fee.taxClass !== undefined ? { taxClass: fee.taxClass } : {}), taxMinor: roundMicrosToMinor(BigInt(fee.taxMicros)),
+      })) } : {}),
+      ...(version === 5 && order.shipping?.length ? { shipping: order.shipping.map((charge) => ({
+        clientShippingId: charge.id, name: charge.name, ...(charge.methodId !== undefined ? { methodId: charge.methodId } : {}),
+        amountMinor: charge.amountMinor, taxStatus: charge.taxStatus,
+        ...(charge.taxClass !== undefined ? { taxClass: charge.taxClass } : {}), taxMinor: roundMicrosToMinor(BigInt(charge.taxMicros)),
+      })) } : {}),
       payments: order.payments.map((payment) => ({
         clientPaymentId: payment.id, method: payment.method, amountMinor: payment.amountMinor,
         ...(payment.tenderedMinor !== undefined ? { tenderedMinor: payment.tenderedMinor } : {}),
@@ -105,9 +117,12 @@ export function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attempt
       ...(discountMinor > 0 ? { discountMinor } : {}),
       taxMinor: order.taxMinor, totalMinor: order.totalMinor,
       ...(version >= 3 ? {
-        display: { ...order.display!, lines: order.display!.lines.map(({ lineId, amountMinor, discounts }) => ({
+        display: { ...storedDisplay, lines: order.display!.lines.map(({ lineId, amountMinor, discounts }) => ({
           clientLineId: lineId, amountMinor, discounts,
-        })) },
+        })),
+        ...(version === 5 && order.display!.fees ? { fees: order.display!.fees.map(({ id, amountMinor }) => ({ clientFeeId: id, amountMinor })) } : {}),
+        ...(version === 5 && order.display!.shipping ? { shipping: order.display!.shipping.map(({ id, amountMinor }) => ({ clientShippingId: id, amountMinor })) } : {}),
+        },
         taxByRate: order.taxByRate!.map(({ ratePpm, code, netMinor, amountMinor, grossMinor }) => ({
           ratePpm, ...(code !== undefined ? { code } : {}), netMinor, taxMinor: amountMinor, grossMinor,
         })),

package/src/pos-order/finalize.ts

@@ -29,7 +29,11 @@ export function withSentForm(order: Order, posOrder: PosOrder): SentOrder {
   if (customer && posOrder.customer?.id === undefined) delete customer.id;
   return { ...order, customer,
     lineItems: order.lineItems.map((line, i) => ({ ...line, name: posOrder.lines[i].name })),
+    ...(order.fees ? { fees: order.fees.map((fee, i) => ({ ...fee, name: posOrder.fees![i].name })) } : {}),
+    ...(order.shipping ? { shipping: order.shipping.map((charge, i) => ({ ...charge, name: posOrder.shipping![i].name })) } : {}),
     display: posOrder.display ? { ...order.display,
+      ...(order.display.fees ? { fees: order.display.fees.map((row, i) => ({ ...row, name: posOrder.display!.fees![i].name })) } : {}),
+      ...(order.display.shipping ? { shipping: order.display.shipping.map((row, i) => ({ ...row, name: posOrder.display!.shipping![i].name })) } : {}),
       lines: order.display.lines.map((line, i) => ({ ...line,
         discounts: line.discounts.map((discount, j) => ({ ...discount, label: posOrder.display!.lines[i].discounts[j].label })),
       })),
@@ -43,7 +47,15 @@ export function freezeSentForm(order: PosOrder): PosOrder {
   const lines = order.lines.map((line) => {
     const name = cutText(line.name, PAYLOAD_STRING_MAX);
     changed ||= name !== line.name;
-    return { ...line, name };
+    const custom = line.custom && { ...line.custom, name: cutText(line.custom.name, PAYLOAD_STRING_MAX) };
+    changed ||= custom !== undefined && custom.name !== line.custom!.name;
+    return { ...line, name, ...(custom ? { custom } : {}) };
+  });
+  const charges = { fees: order.fees, shipping: order.shipping };
+  for (const field of ['fees', 'shipping'] as const) if (charges[field]) charges[field] = charges[field]!.map((charge) => {
+    const name = cutText(charge.name, PAYLOAD_STRING_MAX);
+    changed ||= name !== charge.name;
+    return { ...charge, name };
   });
   const display = order.display && { ...order.display, lines: order.display.lines.map((line) => ({ ...line,
     discounts: line.discounts.map((discount) => {
@@ -53,6 +65,11 @@ export function freezeSentForm(order: PosOrder): PosOrder {
       return { ...discount, label };
     }),
   })) };
+  for (const field of ['fees', 'shipping'] as const) if (display?.[field]) display[field] = display[field]!.map((row) => {
+    const name = cutText(row.name, PAYLOAD_STRING_MAX);
+    changed ||= name !== row.name;
+    return { ...row, name };
+  });
   const payments = order.payments.map((payment) => {
     if (payment.reference === undefined) return payment;
     const reference = cutText(payment.reference, PAYLOAD_STRING_MAX);
@@ -67,7 +84,8 @@ export function freezeSentForm(order: PosOrder): PosOrder {
       if (!localWarnings.some((warning) => warning.code === 'customer_omitted' && warning.field === field)) localWarnings.push({ code: 'customer_omitted', field });
     }
   }
-  return changed ? { ...order, lines, payments, customer, ...(display ? { display } : {}), ...(localWarnings.length ? { localWarnings } : {}) } : order;
+  return changed ? { ...order, lines, payments, customer, ...(charges.fees ? { fees: charges.fees } : {}),
+    ...(charges.shipping ? { shipping: charges.shipping } : {}), ...(display ? { display } : {}), ...(localWarnings.length ? { localWarnings } : {}) } : order;
 }
 
 /**
@@ -94,6 +112,10 @@ export function referenceReason(value: string | undefined): 'long' | 'nul' | nul
  * customer email or id the shape check would refuse is left out, so `toOrderCreateEnvelope` sends it unchanged.
  */
 export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosOrder {
+  if ((order.fees?.length || order.shipping?.length || order.lineItems.some((line) => line.custom))
+    && (options.capabilities?.orderCreate ?? 1) < 5) {
+    throw new Error("finalize: fees, shipping and custom lines need the store to accept order.create version 5; update the store's TallyUI plugin");
+  }
   if (!order.lineItems.length) throw new Error('finalize: no lines');
   // Defence in depth: the builder already clamps every discount to >= 0, so this should never fire.
   if (order.discountMinor < 0
@@ -136,14 +158,20 @@ export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosO
   }
   const newId = options.newId ?? uuidv7;
   const id = newId();
-  const lines = order.lineItems.map((line) => ({
+  const lines: PosOrder['lines'] = order.lineItems.map((line) => ({
     id: newId(), productId: line.productId,
     ...(line.variantId !== undefined ? { variantId: line.variantId } : {}),
+    ...(line.custom ? { custom: { name: line.name, ...(line.sku ? { sku: line.sku } : {}),
+      ...(line.taxClass !== undefined ? { taxClass: line.taxClass } : {}), taxStatus: line.taxStatus ?? 'taxable' } } : {}),
+    ...(line.taxStatus !== undefined ? { taxStatus: line.taxStatus } : {}),
     name: line.name, sku: line.sku, quantity: line.quantity, unitPriceMinor: line.unitPriceMinor,
     discountMinor: line.discountMinor, netMinor: line.netMinor,
+    ...(order.taxRounding?.granularity === 'woocommerce' ? { netMicros: line.netMicros } : {}),
     taxLines: line.taxLines.map((tax) => ({ ...tax })),
     ...(line.priceTaxModeConverted ? { taxInclusive: line.taxInclusive } : {}),
   }));
+  const fees = order.fees?.map((charge) => ({ ...charge, id: newId(), taxLines: charge.taxLines.map((tax) => ({ ...tax })) }));
+  const shipping = order.shipping?.map((charge) => ({ ...charge, id: newId(), taxLines: charge.taxLines.map((tax) => ({ ...tax })) }));
   const payments: PosOrderPayment[] = order.payments.map((payment) => ({
     id: newId(), method: payment.method as PosOrderPayment['method'], amountMinor: payment.amountMinor,
     ...(payment.reference !== undefined ? { reference: payment.reference } : {}),
@@ -179,6 +207,8 @@ export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosO
       throw new Error('finalize: display lines do not match the order lines');
     }
     display = { currency: order.currency, exponent: minorUnitDigits(order.currency), ...order.display,
+      ...(fees?.length ? { fees: order.display.fees!.map((row, i) => ({ ...row, id: fees[i].id })) } : {}),
+      ...(shipping?.length ? { shipping: order.display.shipping!.map((row, i) => ({ ...row, id: shipping[i].id })) } : {}),
       lines: order.display.lines.map((line, i) => ({
         lineId: lines[i].id, amountMinor: line.amountMinor,
         discounts: line.discounts.map(({ discountId, label, amountMinor }) => ({
@@ -186,7 +216,9 @@ export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosO
         })),
       })),
     };
-    taxByRate = taxLinesByRate(order.lineItems, order.taxMinor, undefined, order.taxRounding).map(({ ratePpm, code, netMinor, amountMinor }) => ({
+    const taxedLines = [...order.lineItems, ...[...(order.fees ?? []), ...(order.shipping ?? [])]
+      .map((charge) => ({ ...charge, taxInclusive: order.pricesIncludeTax }))];
+    taxByRate = taxLinesByRate(taxedLines, order.taxMinor, undefined, order.taxRounding).map(({ ratePpm, code, netMinor, amountMinor }) => ({
       ratePpm, ...(code !== undefined ? { code } : {}), netMinor, amountMinor, grossMinor: netMinor + amountMinor,
     }));
     if (display.totalMinor !== order.totalMinor || display.taxMinor !== order.taxMinor
@@ -201,11 +233,13 @@ export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosO
   // absent on the snapshot is the default the figures used; `custom` computes as the default but records itself.
   const rounding = order.taxRounding ?? DEFAULT_TAX_ROUNDING;
   const taxRounding: TaxRounding = rounding.granularity === 'custom' ? { granularity: 'custom' }
+    : rounding.granularity === 'woocommerce' ? { granularity: 'woocommerce', roundAtSubtotal: rounding.roundAtSubtotal }
     : { granularity: rounding.granularity, mode: rounding.mode };
   const now = (options.now ?? new Date()).toISOString();
   return freezeSentForm({
     id, saleId: order.id, createdAt: now, updatedAt: now, commandId: newId(), syncStatus: 'pending',
     currency: order.currency, pricesIncludeTax: order.pricesIncludeTax, lines, payments,
+    ...(fees?.length ? { fees } : {}), ...(shipping?.length ? { shipping } : {}),
     subtotalMinor: order.subtotalMinor, discountMinor: order.discountMinor,
     taxMinor: order.taxMinor, totalMinor: order.totalMinor, taxRounding,
     ...(display && taxByRate ? { display, taxByRate } : {}),

package/src/pos-order/schema.ts

@@ -20,9 +20,12 @@ import type { PosOrder } from './types';
  * nothing else. Its migration sets it on every older row. It is one-way like version 5.
  * Version 7 adds `saleId`, the sale order's id (ADR-072; never sent), and changes nothing else. Its migration is the
  * identity: older orders have no `saleId`. It is one-way like version 6.
+ * Version 8 adds fees, shipping, custom lines (ADR-075) and the woocommerce tax rounding (ADR-076), and changes nothing else.
+ * It also stores the WooCommerce 6dp net (`netMicros`) under the woocommerce rounding (ADR-076 amendment).
+ * Its migration is the identity. It is one-way like version 7.
  */
 export const posOrderSchema: RxJsonSchema<PosOrder> = {
-  version: 7, primaryKey: 'id', type: 'object', additionalProperties: false,
+  version: 8, primaryKey: 'id', type: 'object', additionalProperties: false,
   properties: {
     id: { type: 'string', maxLength: 36 },
     saleId: { type: 'string', maxLength: 36 },
@@ -39,7 +42,13 @@ export const posOrderSchema: RxJsonSchema<PosOrder> = {
       type: 'object', properties: {
         id: { type: 'string', maxLength: 36 }, productId: { type: 'string' }, variantId: { type: 'string' },
         name: { type: 'string' }, sku: { type: 'string' }, quantity: { type: 'integer' },
+        taxStatus: { type: 'string', enum: ['taxable', 'none'] },
+        custom: { type: 'object', additionalProperties: false, properties: {
+          name: { type: 'string', minLength: 1, maxLength: 255 }, sku: { type: 'string', maxLength: 64 },
+          taxClass: { type: 'string', maxLength: 64 }, taxStatus: { type: 'string', enum: ['taxable', 'none'] },
+        }, required: ['name', 'taxStatus'] },
         unitPriceMinor: { type: 'integer' }, discountMinor: { type: 'integer' }, netMinor: { type: 'integer' },
+        netMicros: { type: 'string', pattern: '^-?[0-9]{1,24}$', maxLength: 25 },
         taxLines: { type: 'array', items: {
           type: 'object', properties: { code: { type: 'string' }, ratePpm: { type: 'integer' }, taxMicros: { type: 'string' } },
           required: ['ratePpm', 'taxMicros'],
@@ -47,6 +56,26 @@ export const posOrderSchema: RxJsonSchema<PosOrder> = {
       },
       required: ['id', 'productId', 'name', 'sku', 'quantity', 'unitPriceMinor', 'discountMinor', 'netMinor', 'taxLines'],
     } },
+    fees: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
+      id: { type: 'string', maxLength: 36 }, name: { type: 'string', minLength: 1, maxLength: 255 },
+      amountMinor: { type: 'integer', minimum: 0 }, taxClass: { type: 'string', maxLength: 64 },
+      taxStatus: { type: 'string', enum: ['taxable', 'none'] }, netMinor: { type: 'integer' }, taxMicros: { type: 'string' },
+      netMicros: { type: 'string', pattern: '^-?[0-9]{1,24}$', maxLength: 25 }, totalMinor: { type: 'integer' },
+      taxLines: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
+        code: { type: 'string', maxLength: 255 }, ratePpm: { type: 'integer' }, taxMicros: { type: 'string' },
+        rateId: { type: 'integer' }, compound: { type: 'boolean' },
+      }, required: ['ratePpm', 'taxMicros'] } },
+    }, required: ['id', 'name', 'amountMinor', 'taxStatus', 'taxLines', 'netMinor', 'taxMicros'] } },
+    shipping: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
+      id: { type: 'string', maxLength: 36 }, name: { type: 'string', minLength: 1, maxLength: 255 },
+      methodId: { type: 'string', maxLength: 64 }, amountMinor: { type: 'integer', minimum: 0 }, taxClass: { type: 'string', maxLength: 64 },
+      taxStatus: { type: 'string', enum: ['taxable', 'none'] }, netMinor: { type: 'integer' }, taxMicros: { type: 'string' },
+      netMicros: { type: 'string', pattern: '^-?[0-9]{1,24}$', maxLength: 25 }, totalMinor: { type: 'integer' },
+      taxLines: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
+        code: { type: 'string', maxLength: 255 }, ratePpm: { type: 'integer' }, taxMicros: { type: 'string' },
+        rateId: { type: 'integer' }, compound: { type: 'boolean' },
+      }, required: ['ratePpm', 'taxMicros'] } },
+    }, required: ['id', 'name', 'amountMinor', 'taxStatus', 'taxLines', 'netMinor', 'taxMicros'] } },
     payments: { type: 'array', items: {
       type: 'object', properties: {
         id: { type: 'string', maxLength: 36 }, method: { type: 'string', enum: ['cash', 'external'] },
@@ -70,16 +99,23 @@ export const posOrderSchema: RxJsonSchema<PosOrder> = {
     }, required: ['since', 'reason', 'isolated'] },
     lateSessionId: { type: 'string' },
     taxRounding: { type: 'object', additionalProperties: false, properties: {
-      granularity: { type: 'string', enum: ['per_order', 'per_line_items', 'per_rate_group_items', 'custom'] },
+      granularity: { type: 'string', enum: ['per_order', 'per_line_items', 'per_rate_group_items', 'custom', 'woocommerce'] },
+      roundAtSubtotal: { type: 'boolean' },
       mode: { type: 'string', enum: ['half_away_from_zero', 'half_up'] },
     }, required: ['granularity'] },
-    sentVersion: { type: 'integer', minimum: 1, maximum: 4 },
-    downgradedFrom: { type: 'integer', minimum: 1, maximum: 4 },
+    sentVersion: { type: 'integer', minimum: 1, maximum: 5 },
+    downgradedFrom: { type: 'integer', minimum: 1, maximum: 5 },
     // The nested objects are closed too: loosening a schema later is free, tightening one costs a migration.
     display: { type: 'object', additionalProperties: false, properties: {
       currency: { type: 'string' }, exponent: { type: 'integer' }, taxInclusive: { type: 'boolean' },
       subtotalMinor: { type: 'integer' }, discountMinor: { type: 'integer' }, taxMinor: { type: 'integer' },
       totalMinor: { type: 'integer' }, orderDiscountMinor: { type: 'integer' },
+      fees: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
+        id: { type: 'string', maxLength: 36 }, name: { type: 'string', minLength: 1, maxLength: 255 }, amountMinor: { type: 'integer' },
+      }, required: ['id', 'name', 'amountMinor'] } },
+      shipping: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
+        id: { type: 'string', maxLength: 36 }, name: { type: 'string', minLength: 1, maxLength: 255 }, amountMinor: { type: 'integer' },
+      }, required: ['id', 'name', 'amountMinor'] } },
       lines: { type: 'array', items: {
         type: 'object', additionalProperties: false, properties: {
           lineId: { type: 'string' }, amountMinor: { type: 'integer' },
@@ -129,5 +165,5 @@ export function posOrderCollection(): { schema: RxJsonSchema<PosOrder>; migratio
   // it means no older sale is ever re-rounded (#287).
   const recordRounding = (doc: PosOrder) => { doc.taxRounding ??= { ...DEFAULT_TAX_ROUNDING }; return doc; };
   return { schema: posOrderSchema,
-    migrationStrategies: { 1: identity, 2: identity, 3: identity, 4: identity, 5: recordSent, 6: recordRounding, 7: identity } };
+    migrationStrategies: { 1: identity, 2: identity, 3: identity, 4: identity, 5: recordSent, 6: recordRounding, 7: identity, 8: identity } };
 }

package/src/pos-order/types.ts

@@ -1,5 +1,5 @@
-import type { CommandError, CommandServerRefs, CommandWarning, PaymentMethodKind, TaxRounding } from '@tallyui/core';
-import type { DisplayTotals } from '../order/types';
+import type { CommandError, CommandServerRefs, CommandWarning, OrderCreateLine, PaymentMethodKind, TaxRounding } from '@tallyui/core';
+import type { DisplayTotals, FeeLine, ShippingLine } from '../order/types';
 
 export type PosOrderSyncStatus = 'pending' | 'applied' | 'rejected';
 
@@ -19,6 +19,8 @@ export interface PosOrderLine {
   id: string;
   productId: string;
   variantId?: string;
+  custom?: OrderCreateLine['custom'];
+  taxStatus?: 'taxable' | 'none';
   name: string;
   sku: string;
   quantity: number;
@@ -26,6 +28,7 @@ export interface PosOrderLine {
   /** Line discounts plus the allocated order-discount share, in the line's own tax mode (ADR-062). */
   discountMinor: number;
   netMinor: number;
+  netMicros?: string;
   taxLines: Array<{ code?: string; ratePpm: number; taxMicros: string }>;
   /** This line's own tax mode; set only when it was converted from the store's (ADR-038 amendment). */
   taxInclusive?: boolean;
@@ -48,6 +51,8 @@ export interface PosOrder {
   currency: string;
   pricesIncludeTax: boolean;
   lines: PosOrderLine[];
+  fees?: FeeLine[];
+  shipping?: ShippingLine[];
   subtotalMinor: number;
   discountMinor: number;
   taxMinor: number;
@@ -71,9 +76,9 @@ export interface PosOrder {
    * The order.create version every attempt under this `commandId` goes out at: the outbox records it before the first
    * send, and lowers it only on a downgrade (ADR-065 amendment). Absent means not sent yet (or requeued).
    */
-  sentVersion?: 1 | 2 | 3 | 4;
+  sentVersion?: 1 | 2 | 3 | 4 | 5;
   /** The version first tried, before the downgrade (the order's audit). */
-  downgradedFrom?: 1 | 2 | 3 | 4;
+  downgradedFrom?: 1 | 2 | 3 | 4 | 5;
   /** ADR-065: the receipt's display figures, in integer minor units of `currency` at `exponent`. */
   display?: DisplayTotals & { currency: string; exponent: number };
   /** ADR-065: tax by rate, named as `taxLinesByRate` names them (`amountMinor` is the tax). */

package/src/receipt/build-receipt-data.ts

@@ -5,7 +5,11 @@ import type { ReceiptConfig, ReceiptData } from './types';
 export function buildReceiptData(order: SentOrder, config: ReceiptConfig): ReceiptData {
   // Drops the shared helper's `netMinor` (the Z report's own use): the receipt's tax summary
   // never showed it, and an exact-shape test elsewhere in this package pins that.
-  const taxLines = taxLinesByRate(order.lineItems, order.taxMinor, config.taxLabels, order.taxRounding).map(
+  const taxedLines = [...order.lineItems.map((line) => order.taxRounding?.granularity === 'woocommerce' && line.netMicros !== undefined
+    ? { ...line, taxInclusive: order.pricesIncludeTax } : line), ...[...(order.fees ?? []), ...(order.shipping ?? [])].map((charge) => ({
+    ...charge, taxInclusive: order.pricesIncludeTax,
+  }))];
+  const taxLines = taxLinesByRate(taxedLines, order.taxMinor, config.taxLabels, order.taxRounding).map(
     ({ label, code, ratePpm, amountMinor }) => ({ label, code, ratePpm, amountMinor }),
   );
 
@@ -15,6 +19,7 @@ export function buildReceiptData(order: SentOrder, config: ReceiptConfig): Recei
   let taxSoFar = order.lineItems.reduce(
     (sum, li) => li.taxInclusive || li.priceTaxModeConverted ? sum : sum + BigInt(li.taxMicros), 0n);
   const lineTotals = order.lineItems.map((li) => {
+    if (order.taxRounding?.granularity === 'woocommerce' && li.netMicros !== undefined) return order.pricesIncludeTax ? li.totalMinor! : li.netMinor;
     if (!li.priceTaxModeConverted) return li.netMinor;
     const share = roundMicrosToMinor(taxSoFar + BigInt(li.taxMicros)) - roundMicrosToMinor(taxSoFar);
     taxSoFar += BigInt(li.taxMicros);
@@ -48,6 +53,8 @@ export function buildReceiptData(order: SentOrder, config: ReceiptConfig): Recei
       label: label(d),
       amountMinor: d.amountMinor,
     })),
+    fees: (order.display.fees ?? []).map(({ name, amountMinor }) => ({ name, amountMinor })),
+    shipping: (order.display.shipping ?? []).map(({ name, amountMinor }) => ({ name, amountMinor })),
     orderDiscountMinor: order.display.orderDiscountMinor,
     totals: {
       taxInclusive: order.display.taxInclusive,

package/src/receipt/types.ts

@@ -21,6 +21,8 @@ export interface ReceiptData {
     register?: string;
   };
   lineItems: ReceiptLineItem[];
+  fees: Array<{ name: string; amountMinor: number }>;
+  shipping: Array<{ name: string; amountMinor: number }>;
   discounts: { label: string; amountMinor: number }[];
   orderDiscountMinor: number;   // the order discounts as one row, in the display mode; + Σ displayDiscounts = totals.discountMinor
   totals: {

package/src/register/closure-document.ts

@@ -172,7 +172,7 @@ function envelope<R extends Values>(row: R, context: ClosureContext, xreport = f
   return {
     closure: {
       has_sales:
-        row.period_sales_total != null || row.period_refunds_total != null || Number(breakdowns.transaction_count) > 0,
+        Number(breakdowns.transaction_count ?? 0) > 0 || Number(row.period_sales_total || 0) !== 0 || Number(row.period_refunds_total || 0) !== 0,
       has_perpetual: row.perpetual_sales_total != null || row.perpetual_refunds_total != null,
       ...Object.fromEntries(
         ['payment_methods', 'tax_rates', 'movements'].map((key) => [`has_${key}`, Object.keys((breakdowns[key] as Values) ?? {}).length > 0]),

package/src/register/session-store.ts

@@ -481,8 +481,8 @@ export async function writeClosure({
   for (const order of bound) {
     // Grouped by the rule applied: a `custom` sale used the default figures, so it joins the default's group.
     const recorded = order.taxRounding ?? DEFAULT_TAX_ROUNDING;
-    const { granularity, mode } = recorded.granularity === 'custom' ? DEFAULT_TAX_ROUNDING : recorded;
-    roundings.add(`${granularity} ${mode}`);
+    const rounding = recorded.granularity === 'custom' ? DEFAULT_TAX_ROUNDING : recorded;
+    roundings.add(rounding.granularity === 'woocommerce' ? `woocommerce ${rounding.roundAtSubtotal}` : `${rounding.granularity} ${rounding.mode}`);
     const lines = order.lines.map((line) => ({ ...line, taxInclusive: line.taxInclusive ?? order.pricesIncludeTax }));
     for (const { ratePpm, netMinor, amountMinor } of taxLinesByRate(lines, order.taxMinor, undefined, order.taxRounding)) {
       const existing = taxRates.get(String(ratePpm));

package/src/sale/cart.ts

@@ -19,5 +19,6 @@ export function addEntryToCart<Doc>(builder: OrderBuilder, entry: CatalogueEntry
     productId: traits.getId(product), variantId: variant.id, name,
     sku: variant.sku ?? '', imageUrl: traits.getImageUrl?.(product), unitPrice,
     taxClass: traits.getTaxClass?.(product, variant.id),
+    ...(traits.getTaxStatus?.(product, variant.id) === 'none' ? { taxStatus: 'none' as const } : {}),
   });
 }

package/src/sale/use-sale.ts

@@ -1,8 +1,8 @@
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import type { RxCollection } from 'rxdb';
 import type { ProductTraits, ServerCapabilities, StoreSettings } from '@tallyui/core';
-import { createOrderBuilder, writeOrderDraft, restoreOrderDraft, type OrderBuilder, type CustomerSummary, type Discount, type Order, type SentOrder } from '../order';
-import { finalizeOrder, type PosOrder } from '../pos-order';
+import { createOrderBuilder, writeOrderDraft, restoreOrderDraft, type ChargeInput, type OrderBuilder, type CustomerSummary, type Discount, type Order, type SentOrder } from '../order';
+import { finalizeOrder, uuidv7, type PosOrder } from '../pos-order';
 import { MESSAGE_NAME_MAX, referenceError, referenceReason, withSentForm } from '../pos-order/finalize';
 import { CUSTOMER_REFUSALS, customerRefusal, cutText, PAYLOAD_STRING_MAX } from '../pos-order/command';
 import { useTax } from '../tax';
@@ -137,12 +137,12 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
   }, [rendered]);
   // New tax settings or currency wait until the sale is idle (an empty cart), then start a new sale keeping its customer:
   // a sale in progress (lines, tender or receipt) finishes on the settings it started with (a money rule).
-  const idle = stage.kind === 'cart' && !order.lineItems.length;
+  const idle = stage.kind === 'cart' && !order.lineItems.length && !order.fees?.length && !order.shipping?.length;
   // A layout effect, on live idleness (#301): it runs inside the settings' commit, before any tap can be handled, and
   // the rendered `idle` would miss a line added since this render (it would then be dropped with the old builder).
   useLayoutEffect(() => {
     const live = builderNow.current.getSnapshot();
-    const liveIdle = stageNow.current.kind === 'cart' && !live.lineItems.length && !inFlight.current && !pending.current;
+    const liveIdle = stageNow.current.kind === 'cart' && !live.lineItems.length && !live.fees?.length && !live.shipping?.length && !inFlight.current && !pending.current;
     if (liveIdle && (madeWith.current.taxContext !== taxContext || madeWith.current.currency !== settings.currency)) resetSale(live.customer ?? null);
   });
   // A screen that unmounts (medusapos: Sign out) mid-save must still leave a trace of the loss.
@@ -275,6 +275,50 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
       }
     },
     setQuantity(lineId: string, quantity: number) { if (!locked()) builderNow.current.updateQuantity(lineId, quantity); },
+    /** ADR-075: adds a fee; returns its id or the builder's refusal. */
+    addFee(input: ChargeInput): { id: string } | string {
+      if (locked()) return SALE_SAVING;
+      try { return { id: builderNow.current.addFee(input) }; }
+      catch (error) { if (error instanceof Error) return error.message; throw error; }
+    },
+    /** ADR-075: updates a fee; returns a refusal or null. */
+    updateFee(id: string, patch: Partial<ChargeInput>): string | null {
+      if (locked()) return SALE_SAVING;
+      try { builderNow.current.updateFee(id, patch); return null; }
+      catch (error) { if (error instanceof Error) return error.message; throw error; }
+    },
+    /** ADR-075: removes a fee; returns a refusal or null. */
+    removeFee(id: string): string | null {
+      if (locked()) return SALE_SAVING;
+      try { builderNow.current.removeFee(id); return null; }
+      catch (error) { if (error instanceof Error) return error.message; throw error; }
+    },
+    /** ADR-075: adds shipping; returns its id or the builder's refusal. */
+    addShipping(input: ChargeInput & { methodId?: string }): { id: string } | string {
+      if (locked()) return SALE_SAVING;
+      try { return { id: builderNow.current.addShipping(input) }; }
+      catch (error) { if (error instanceof Error) return error.message; throw error; }
+    },
+    /** ADR-075: updates shipping; returns a refusal or null. */
+    updateShipping(id: string, patch: Partial<ChargeInput & { methodId?: string }>): string | null {
+      if (locked()) return SALE_SAVING;
+      try { builderNow.current.updateShipping(id, patch); return null; }
+      catch (error) { if (error instanceof Error) return error.message; throw error; }
+    },
+    /** ADR-075: removes shipping; returns a refusal or null. */
+    removeShipping(id: string): string | null {
+      if (locked()) return SALE_SAVING;
+      try { builderNow.current.removeShipping(id); return null; }
+      catch (error) { if (error instanceof Error) return error.message; throw error; }
+    },
+    /** ADR-075: adds a distinct custom product line; returns its id or the builder's refusal. */
+    addCustomLine(input: { name: string; priceMinor: number; quantity?: number; taxClass?: string; taxStatus?: 'taxable' | 'none'; sku?: string }): { id: string } | string {
+      if (locked()) return SALE_SAVING;
+      try {
+        return { id: builderNow.current.addLine({ ...input, custom: true, productId: `custom:${uuidv7()}`,
+          unitPrice: { amount: input.priceMinor, currency: madeWith.current.currency.toUpperCase() } }) };
+      } catch (error) { if (error instanceof Error) return error.message; throw error; }
+    },
     /** Sets a line's unit price in minor units of its own tax mode, recomputing discounts and tax; returns a refusal or null. */
     setUnitPrice(lineId: string, amountMinor: number): string | null {
       if (locked()) return SALE_SAVING;
@@ -435,7 +479,7 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
       if (stageNow.current.kind !== 'cart') return 'Finish or cancel the payment before parking the sale';
       const builder = builderNow.current;
       const snapshot = builder.getSnapshot();
-      if (!snapshot.lineItems.length) return 'There is nothing to park';
+      if (!snapshot.lineItems.length && !snapshot.fees?.length && !snapshot.shipping?.length) return 'There is nothing to park';
       await writeOrderDraft(opts.drafts, snapshot);
       if (builderNow.current !== builder || builder.getSnapshot() !== snapshot) return 'The sale changed while it was being parked; park it again';
       resetSale(null);
@@ -447,7 +491,7 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
       if (!opts.drafts) throw new Error('useSale: resume() needs the drafts option');
       const live = builderNow.current;
       const liveSnapshot = live.getSnapshot();
-      if (stageNow.current.kind !== 'cart' || liveSnapshot.lineItems.length) return 'Park or clear the current sale first';
+      if (stageNow.current.kind !== 'cart' || liveSnapshot.lineItems.length || liveSnapshot.fees?.length || liveSnapshot.shipping?.length) return 'Park or clear the current sale first';
       const doc = await opts.drafts.findOne(draftId).exec();
       if (!doc) return 'That parked sale is no longer there';
       const saved: Order = JSON.parse(doc.toJSON().data);

package/src/store-settings/map-store-settings.ts

@@ -14,5 +14,9 @@ export function withPricingContext(context: SyncContext, settings: StoreSettings
  */
 export function taxProviderProps(settings: StoreSettings): Omit<TaxProviderProps, 'children'> {
   const rounding = settings.taxRounding?.granularity === 'custom' ? undefined : settings.taxRounding;
-  return { ratesPpm: settings.taxRatesPpm, pricesIncludeTax: settings.pricesIncludeTax, ...(rounding && { rounding }), ...(settings.taxRateCodes && { rateCodes: settings.taxRateCodes }) };
+  return { ratesPpm: settings.taxRatesPpm, pricesIncludeTax: settings.pricesIncludeTax, ...(rounding && { rounding }), ...(settings.taxRateCodes && { rateCodes: settings.taxRateCodes }),
+    ...(settings.taxRates && { taxRates: settings.taxRates }),
+    ...(settings.taxRoundAtSubtotal !== undefined && { taxRoundAtSubtotal: settings.taxRoundAtSubtotal }),
+    ...(settings.shippingTaxClass !== undefined && { shippingTaxClass: settings.shippingTaxClass }),
+    ...(settings.taxClassSlugs && { taxClassSlugs: settings.taxClassSlugs }) };
 }

package/src/tax/exact.ts

@@ -1,4 +1,5 @@
 import type { TaxRounding } from '@tallyui/core';
+import { woocommerceTaxByRate } from '../order/woocommerce-tax';
 
 /** Micro-minor-units per minor unit. */
 export const MICROS_PER_MINOR = 1_000_000n;
@@ -122,7 +123,7 @@ export interface RateTaxLine {
   amountMinor: number;
 }
 
-type TaxedLine = { netMinor: number; discountMinor?: number; taxInclusive: boolean; taxLines: readonly { code?: string; ratePpm: number; taxMicros: string }[] };
+type TaxedLine = { netMinor: number; netMicros?: string; discountMinor?: number; taxInclusive: boolean; taxLines: readonly { code?: string; ratePpm: number; taxMicros: string }[] };
 
 /**
  * A `per_line_items` or `per_rate_group_items` store's figures (#287) as @vendure/core 3.7.3 computes them; undefined
@@ -186,6 +187,7 @@ export function taxLinesByRate(
   taxLabels?: Record<number, string>,
   rounding?: TaxRounding,
 ): RateTaxLine[] {
+  if (rounding?.granularity === 'woocommerce' && lines.every((line) => line.netMicros !== undefined)) return woocommerceTaxByRate(lines, rounding.roundAtSubtotal, taxLabels, orderTaxMinor);
   const label = (ratePpm: number) => taxLabels?.[ratePpm] ?? `Tax ${ratePpm / 10000}%`;
   const rounded = roundedTaxByRate(lines, rounding);
   if (rounded) return rounded.rates.map(({ code, ratePpm, netMinor, amountMinor }) => ({ label: label(ratePpm), code, ratePpm, netMinor, amountMinor }));

package/src/tax/index.ts

@@ -2,4 +2,4 @@ export { MICROS_PER_MINOR, ratePpmFromPercent, taxMicros, roundMicrosToMinor, co
 export type { TaxLineInput, OrderTaxTotals, RateTaxLine } from './exact';
 export { TaxProvider, useTax, taxLogger } from './tax-provider';
 export type { TaxProviderProps } from './tax-provider';
-export type { TaxRateMap, TaxContext } from './types';
+export type { TaxRateMap, TaxContext, WooRate } from './types';

package/src/tax/tax-provider.tsx

@@ -1,6 +1,6 @@
 import { createContext, useContext, useMemo } from 'react';
 import type { ReactNode } from 'react';
-import type { TaxRounding } from '@tallyui/core';
+import { woocommerceTax, type StoreSettings, type TaxRounding } from '@tallyui/core';
 import type { TaxContext } from './types';
 import { createLogger } from '../logging';
 
@@ -8,7 +8,8 @@ export const taxLogger = createLogger('tax');
 
 const TaxCtx = createContext<TaxContext | null>(null);
 
-export interface TaxProviderProps {
+export interface TaxProviderProps extends Pick<StoreSettings, 'taxRoundAtSubtotal' | 'shippingTaxClass' | 'taxClassSlugs'> {
+  taxRates?: StoreSettings['taxRates'];
   ratesPpm: Record<string, number>;
   pricesIncludeTax: boolean;
   /** `ServerCapabilities.taxRounding` (#287); a change restarts an idle sale under it. */
@@ -18,7 +19,7 @@ export interface TaxProviderProps {
   children: ReactNode;
 }
 
-export function TaxProvider({ ratesPpm, pricesIncludeTax, rounding, rateCodes, children }: TaxProviderProps) {
+export function TaxProvider({ ratesPpm, pricesIncludeTax, rounding, rateCodes, taxRates, children }: TaxProviderProps) {
   const value = useMemo<TaxContext>(
     () => {
       if (Object.values(ratesPpm).some((rate) => !Number.isSafeInteger(rate) || rate < 0)) {
@@ -26,6 +27,8 @@ export function TaxProvider({ ratesPpm, pricesIncludeTax, rounding, rateCodes, c
       }
       const unknown = new Set<string>();
       return {
+        ...(taxRates ? { getTaxRates: (taxClass?: string, options?: { shipping?: boolean }) =>
+          (taxRates[woocommerceTax.normalizeTaxClass(taxClass)] ?? []).filter((rate) => !options?.shipping || rate.shipping) } : {}),
         getTaxRatePpm: (taxClass) => {
           if (taxClass !== undefined && Object.hasOwn(ratesPpm, taxClass)) return ratesPpm[taxClass];
           // A class the store's rates don't key is taxed at the default rate; warn once per class and rate map.
@@ -44,7 +47,7 @@ export function TaxProvider({ ratesPpm, pricesIncludeTax, rounding, rateCodes, c
         ...(rounding ? { rounding } : {}),
       };
     },
-    [ratesPpm, pricesIncludeTax, rounding, rateCodes],
+    [ratesPpm, pricesIncludeTax, rounding, rateCodes, taxRates],
   );
 
   return <TaxCtx.Provider value={value}>{children}</TaxCtx.Provider>;

package/src/tax/types.ts

@@ -1,4 +1,6 @@
-import type { TaxRounding } from '@tallyui/core';
+import type { StoreSettings, TaxRounding } from '@tallyui/core';
+
+export type WooRate = NonNullable<StoreSettings['taxRates']>[string][number];
 
 /** Tax rates as integer parts per million (19% = 190000). */
 export type TaxRateMap = {
@@ -7,6 +9,7 @@ export type TaxRateMap = {
 };
 
 export interface TaxContext {
+  getTaxRates?(taxClass?: string, options?: { shipping?: boolean }): readonly WooRate[];
   /** Tax rate for a tax class as integer parts per million (19% = 190000); the default class when omitted or unknown. */
   getTaxRatePpm(taxClass?: string): number;
   /** The backend's name for that class's rate, when mapped: a `per_rate_group_items` store groups by name and value (#287). */