@tallyui/pos 3.2.1 → 3.3.0

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,8 @@ 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 taxedLines = [...order.lineItems, ...[...(order.fees ?? []), ...(order.shipping ?? [])].map((charge) => ({
+  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(
@@ -18,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);

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/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). */