@tallyui/pos 2.0.0 → 3.0.0-next.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/pos",
-  "version": "2.0.0",
+  "version": "3.0.0-next.1",
   "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": "2.0.0",
+    "@tallyui/core": "^3.0.0-next.1",
     "react": ">=18",
-    "rxdb": ">=16",
+    "rxdb": "~17.5.0",
     "rxjs": ">=7"
   },
   "devDependencies": {
-    "@tallyui/core": "2.0.0",
+    "@tallyui/core": "3.0.0-next.1",
     "@types/react": ">=18",
     "react": "^19.2.4",
-    "rxdb": "16.21.1",
+    "rxdb": "17.5.0",
     "rxjs": "7.8.2",
-    "@tallyui/connector-medusa": "2.0.0",
-    "@tallyui/connector-woocommerce": "2.0.0",
-    "@tallyui/database": "2.0.0"
+    "@tallyui/connector-medusa": "3.0.0-next.1",
+    "@tallyui/connector-woocommerce": "3.0.0-next.1",
+    "@tallyui/database": "3.0.0-next.1"
   },
   "scripts": {
     "build": "tsup",

package/src/index.ts

@@ -7,7 +7,7 @@ export { CurrencyProvider, useCurrencyFormatter, useCurrencyCode } from './curre
 export type { CurrencyProviderProps } from './currency';
 
 // Tax
-export { TaxProvider, useTax } from './tax';
+export { TaxProvider, useTax, taxLogger } from './tax';
 export { MICROS_PER_MINOR, ratePpmFromPercent, taxMicros, roundMicrosToMinor, computeOrderTax, taxLinesByRate } from './tax';
 export type { TaxLineInput, OrderTaxTotals, RateTaxLine } from './tax';
 export type { TaxProviderProps } from './tax';
@@ -25,11 +25,13 @@ export { createRepository } from './repository';
 export type { Repository } from './repository';
 
 // Order
-export { createOrderBuilder, createOrderManager, allocateOrderDiscount } from './order';
+export { createOrderBuilder, createOrderManager, allocateOrderDiscount, taxFiguresForBasket } from './order';
+export type { BasketLine } from './order';
 export type { OrderBuilder, OrderBuilderOptions } from './order';
 export type { OrderManager, OrderManagerOptions, ParkedOrderSummary } from './order';
 export type {
   Order,
+  SentOrder,
   LineItem,
   LineTaxLine,
   AddLineInput,
@@ -53,9 +55,13 @@ export { searchProducts, withStockOverlay, getProductStock, stockOverlay$, stock
 export { useSale, DISCOUNTS_UNSUPPORTED, SALE_SAVING, saleLogger, addEntryToCart, CartError, catalogueEntries, findEntryByCode, variantPriceLabel } from './sale';
 export type { SaleStage, CatalogueEntry } from './sale';
 
-export { uuidv7, finalizeOrder, toOrderCreateEnvelope, posOrderSchema, posOrderCollection, addPosOrderCollection, PosOrderOpenClosedError, posOrdersLogger, getDeviceId, needsAttention, sameSale, OrderContentMismatchError } from './pos-order';
-export type { PosOrderSyncStatus, PosOrderLine, PosOrderPayment, PosOrder, FinalizeOptions } from './pos-order';
+export { uuidv7, finalizeOrder, toOrderCreateEnvelope, UnsupportedOrderVersionError, posOrderSchema, posOrderCollection, addPosOrderCollection, PosOrderOpenClosedError, posOrdersLogger, getDeviceId, needsAttention, sameSale, OrderContentMismatchError } from './pos-order';
+export type { PosOrderSyncStatus, PosOrderLine, PosOrderPayment, PosOrderLocalWarning, PosOrderServerFailures, PosOrder, FinalizeOptions } from './pos-order';
 export { createHttpCommandTransport, createOrderOutbox, useOrderOutbox, outboxLogger } from './outbox';
+export { createRegisterOutbox } from './outbox';
+export type { RegisterOutboxOptions, RegisterOutbox } 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 { 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';
@@ -65,11 +71,13 @@ export { normalizeAmount, isServerDecimal, movementFieldError, deriveExpected, p
 export type { MovementType, LedgerRow, Movement } from './register';
 export { registerSessionSchema, registerSessionCollection, cashMovementSchema, closureSchema } from './register';
 export type { RegisterSession, CashMovement, Closure } from './register';
-export { mintUuid, readRegister, ensureRegister, observeRegister$, getBoundRegisterId, readBoundRegister, bindRegister, unbindRegister, nextSaleCounter, mintClosureNumber, advancePerpetual } from './register';
+export { registerCommandSchema, registerCommandCollection, registerCommandsLogger, sessionOpenCommand, sessionTransitionCommand, movementCommand, closureCommand, reconcileRegisterCommands } from './register';
+export type { RegisterCommand, RegisterCommandCollection } from './register';
+export { mintUuid, readRegister, ensureRegister, observeRegister$, getBoundRegisterId, readBoundRegister, bindRegister, unbindRegister, nextSaleCounter, mintClosureNumber, advancePerpetual, RegisterIdInvalidError } from './register';
 export type { RegisterHost, RegisterCounters, RegisterBucket, RegisterStore, RegisterDocument } from './register';
-export { RegisterSessionRequiredError, RegisterSessionClosedError, RegisterMovementStrandedError, openSessionSelector, requireOpenSession, stampSession, openSession, startCounting, backToSelling, closeSession, recordMovement, voidMovement, writeClosure } from './register';
+export { RegisterSessionRequiredError, RegisterSessionClosedError, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, openSessionSelector, requireOpenSession, stampSession, openSession, startCounting, backToSelling, closeSession, recordMovement, voidMovement, writeClosure } from './register';
 export type { RegisterSessionCollection, CashMovementCollection, ClosureCollection } from './register';
 export { deriveSettled, exportCsv, labelKeys, clampClosureScope, selectClosureRows } from './register';
 export type { Correction, RecordedFigures, ClosureScope } from './register';
-export { minorToDecimal, formatClosureDate, buildClosureDocument, buildXReportDocument, registerFactsLogger, recordRegisterFact, type ClosureContext, type Actor, type RegisterFact } from './register';
+export { minorToDecimal, formatClosureDate, buildClosureDocument, buildXReportDocument, TAX_ROUNDING_MIXED_NOTE, registerFactsLogger, recordRegisterFact, type ClosureContext, type Actor, type RegisterFact } from './register';
 export { useRegisterSession, RegisterTenderInProgressError, RegisterSessionAlreadyOpenError, RegisterCloseIncompleteError, RegisterApprovalRequiredError, type UseRegisterSessionOptions } from './register';

package/src/order/index.ts

@@ -1,10 +1,13 @@
 export { createOrderBuilder } from './order-builder';
+export { taxFiguresForBasket } from './tax-figures';
+export type { BasketLine } from './tax-figures';
 export { allocateOrderDiscount } from './allocate-order-discount';
 export type { OrderBuilder, OrderBuilderOptions } from './order-builder';
 export { createOrderManager } from './order-manager';
 export type { OrderManager, OrderManagerOptions, ParkedOrderSummary } from './order-manager';
 export type {
   Order,
+  SentOrder,
   LineItem,
   LineTaxLine,
   AddLineInput,

package/src/order/order-builder.ts

@@ -1,7 +1,8 @@
 import { BehaviorSubject, type Observable } from 'rxjs';
-import { resolvePrice, type ProductTraits } from '@tallyui/core';
+import { resolvePrice, type ProductTraits, type TaxRounding } from '@tallyui/core';
 import type { TaxContext } from '../tax/types';
-import { taxMicros, roundMicrosToMinor } from '../tax/exact';
+import { taxMicros, roundMicrosToMinor, roundedTaxByRate } from '../tax/exact';
+import { taxLogger } from '../tax/tax-provider';
 import { allocateOrderDiscount } from './allocate-order-discount';
 import type {
   Order,
@@ -13,6 +14,9 @@ import type {
   AddLineInput,
 } from './types';
 
+/** Tax contexts already warned that per_rate_group_items fell back to per_order for inclusive lines (#287). */
+const perRateGroupWarned = new WeakSet<TaxContext>();
+
 let nextId = 0;
 function uid(): string {
   return `${Date.now()}-${++nextId}`;
@@ -23,14 +27,18 @@ function roundHalfAway(n: number): number {
 }
 
 /** The settlement totals of recalculated lines; the display figures derive from them (ADR-063). */
-function sumLines(lines: LineItem[]): { subtotalMinor: number; taxMinor: number; totalMinor: number } {
+function sumLines(lines: LineItem[], 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) };
+  const mode = rounding?.granularity === 'per_order' ? rounding.mode : undefined;
   const netMinor = lines.reduce((sum, li) => sum + li.netMinor, 0);
   const lineTaxMicros = lines.reduce((sum, li) => sum + BigInt(li.taxMicros), 0n);
   const exclusiveTaxMicros = lines.reduce((sum, li) => li.taxInclusive ? sum : sum + BigInt(li.taxMicros), 0n);
-  const taxMinor = roundMicrosToMinor(lineTaxMicros);
+  const taxMinor = roundMicrosToMinor(lineTaxMicros, mode);
   // Each line pays in its own mode: an inclusive line its gross, an exclusive line its net plus tax.
   // The totals sum the lines as recalculated; nothing is subtracted after tax.
-  const linesTotal = netMinor + roundMicrosToMinor(exclusiveTaxMicros);
+  const linesTotal = netMinor + roundMicrosToMinor(exclusiveTaxMicros, mode);
   return { subtotalMinor: linesTotal - taxMinor, taxMinor, totalMinor: Math.max(0, linesTotal) };
 }
 
@@ -158,7 +166,11 @@ 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);
+    const { subtotalMinor, taxMinor, totalMinor } = sumLines(lines, taxContext.rounding);
+    if (taxContext.rounding?.granularity === 'per_rate_group_items' && lines.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)');
+    }
     const discountMinor = lines.reduce((sum, li) => sum + li.discountMinor, 0);
     // Display figures (ADR-063): every discount the cashier entered, and each line's order share, converted on its own
     // into the display mode. A line in the display mode shows quantity × unit price; a converted line shows its
@@ -239,6 +251,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
       changeDueMinor,
       currency,
       pricesIncludeTax: taxContext.pricesIncludeTax,
+      ...(taxContext.rounding ? { taxRounding: taxContext.rounding } : {}),
       createdAt: now,
       updatedAt: new Date().toISOString(),
     };
@@ -254,7 +267,9 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     if (unitPrice.currency !== currency) throw new RangeError('Line currency must match ' + currency);
     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');
-    const taxRates = input.taxRates ?? [{ ratePpm: taxContext.getTaxRatePpm() }];
+    // 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 taxInclusive = unitPrice.taxInclusive ?? taxContext.pricesIncludeTax;
 
     const existing = lineItems.find(
@@ -324,6 +339,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
         imageUrl: traits.getImageUrl(doc),
         unitPrice,
         quantity: opts?.quantity,
+        taxClass: traits.getTaxClass?.(doc, opts?.variantId),
       });
     },
 

package/src/order/order-manager.ts

@@ -1,6 +1,7 @@
 import { BehaviorSubject, map, type Observable } from 'rxjs';
 import type { RxCollection } from 'rxdb';
 import type { TaxContext } from '../tax/types';
+import { customerRefusal } from '../pos-order/command';
 import { createOrderBuilder, type OrderBuilder } from './order-builder';
 import type { Order } from './types';
 
@@ -91,7 +92,8 @@ export function createOrderManager(options: OrderManagerOptions): OrderManager {
       });
 
       // Restore state from saved order
-      if (savedOrder.customer) {
+      // A customer whose email or id order.create would refuse (see useSale's setCustomer) isn't restored.
+      if (savedOrder.customer && !customerRefusal(savedOrder.customer)) {
         builder.setCustomer(savedOrder.customer);
       }
       if (savedOrder.note) {

package/src/order/tax-figures.ts

@@ -0,0 +1,23 @@
+import type { TaxRounding } from '@tallyui/core';
+import { createOrderBuilder } from './order-builder';
+import { taxLinesByRate } from '../tax/exact';
+
+/** A sent line; `discountMinor` is its `lines[].discountMinor` (line discounts + its order share), in its own mode. */
+export type BasketLine = { unitPriceMinor: number; quantity: number; discountMinor?: number; taxInclusive: boolean; taxLines: Array<{ code?: string; ratePpm: number }> };
+
+/**
+ * The till's settlement figures for a sent basket under a store's strategy (#287), computed exactly as a sale computes
+ * them, so a backend can score its own orders against the till (vendurepos/app#38). Each discountMinor is applied as a
+ * fixed line discount in the line's own mode.
+ */
+export function taxFiguresForBasket(currency: string, pricesIncludeTax: boolean, lines: readonly BasketLine[], rounding?: TaxRounding) {
+  const code = currency.toUpperCase();
+  const builder = createOrderBuilder({ currency: code, taxContext: { getTaxRatePpm: () => 0, pricesIncludeTax, ...(rounding ? { rounding } : {}) } });
+  lines.forEach((line, index) => {
+    const lineId = builder.addLine({ productId: `line-${index}`, name: `Line ${index}`, quantity: line.quantity,
+      unitPrice: { amount: line.unitPriceMinor, currency: code, taxInclusive: line.taxInclusive }, taxRates: line.taxLines });
+    if (line.discountMinor) builder.applyLineDiscount(lineId, { type: 'fixed', value: line.discountMinor });
+  });
+  const { subtotalMinor, taxMinor, totalMinor, lineItems, taxRounding } = builder.getSnapshot();
+  return { subtotalMinor, taxMinor, totalMinor, taxByRate: taxLinesByRate(lineItems, taxMinor, undefined, taxRounding) };
+}

package/src/order/types.ts

@@ -1,4 +1,4 @@
-import type { Money } from '@tallyui/core';
+import type { Money, TaxRounding } from '@tallyui/core';
 
 export interface Order {
   id: string;
@@ -10,10 +10,12 @@ export interface Order {
   note: string;
   currency: string;
   pricesIncludeTax: boolean;
+  /** The store's tax rounding strategy the figures were computed with (#287), from the sale's tax context; absent is per_order. */
+  taxRounding?: TaxRounding;
   // Settlement figures, sent in `order.create` (ADR-038, ADR-062). Show `display` instead (ADR-063).
   subtotalMinor: number;      // settlement: excl. tax, after line and order discounts (both pre-tax, ADR-062)
   discountMinor: number;      // settlement: Σ lineItems[].discountMinor, each in its line's own mode, so it mixes modes; not for display
-  taxMinor: number;           // settlement: rounded once per order
+  taxMinor: number;           // settlement: rounded once per order, unless taxRounding says otherwise (#287)
   totalMinor: number;         // settlement: what the customer pays
   display: DisplayTotals;
   paidMinor: number;
@@ -23,6 +25,9 @@ export interface Order {
   updatedAt: string;
 }
 
+/** An Order as it was stored and sent, whose customer id may have been left out. */
+export type SentOrder = Omit<Order, 'customer'> & { customer: (Omit<CustomerSummary, 'id'> & { id?: string }) | null };
+
 /**
  * Figures for showing the cart or a receipt in the store's display mode (ADR-063); never sent to the server.
  * A parked order's saved draft may carry them; they are recomputed from the lines on resume, so never authoritative.
@@ -114,5 +119,6 @@ export interface AddLineInput {
   imageUrl?: string;
   unitPrice: Money & { taxInclusive?: boolean }; // currency must equal the order currency; taxInclusive wins over the order's pricesIncludeTax
   quantity?: number;          // default 1
-  taxRates?: Array<{ code?: string; ratePpm: number }>; // default: [{ ratePpm: from taxContext }]
+  taxRates?: Array<{ code?: string; ratePpm: number }>; // default: [{ ratePpm: taxContext's rate for taxClass }]
+  taxClass?: string;          // the product's tax class (ProductTraits.getTaxClass); ignored when taxRates is given
 }

package/src/outbox/backend-not-found.ts

@@ -0,0 +1,27 @@
+import { BehaviorSubject, type Observable } from 'rxjs';
+import type { OutboxState, TransportOutcome } from './types';
+
+// Consecutive 404 answers before backendMissing tells the cashier; fewer may be a deploy blip.
+const NOT_FOUND_BEFORE_NOTICE = 3;
+
+/** Counts consecutive 404s across every outbox given it, so a missing plugin shows once, whichever outbox meets it. */
+export interface BackendNotFound {
+  /** A 404 counts; any other answer from the store clears; offline (`network`) changes nothing. */
+  record(outcome: TransportOutcome, at: number): void;
+  backendMissing$: Observable<OutboxState['backendMissing']>;
+}
+
+export function createBackendNotFound(): BackendNotFound {
+  let count = 0;
+  let since = 0; // when the first of the consecutive 404s arrived
+  const backendMissing$ = new BehaviorSubject<OutboxState['backendMissing']>(undefined);
+  return {
+    backendMissing$,
+    record(outcome, at) {
+      if (outcome.kind === 'retry' && outcome.reason === 'network') return;
+      if (outcome.kind === 'retry' && outcome.reason === 'status_404') { if (count++ === 0) since = at; } else count = 0;
+      const missing = count >= NOT_FOUND_BEFORE_NOTICE;
+      if (missing !== !!backendMissing$.value) backendMissing$.next(missing ? { since } : undefined);
+    },
+  };
+}

package/src/outbox/http-transport.ts

@@ -1,4 +1,4 @@
-import { COMMANDS_PATH, PROTOCOL_HEADER, PROTOCOL_VERSION, isCommandBatchResponse } from '@tallyui/core';
+import { COMMANDS_PATH, PROTOCOL_HEADER, PROTOCOL_VERSION, isCommandBatchResponse, type AnyCommandEnvelope } from '@tallyui/core';
 import type { CommandTransport } from './types';
 
 // These HTTP statuses permanently refuse the entire command batch.
@@ -11,7 +11,7 @@ export interface HttpTransportOptions {
   timeoutMs?: number;
 }
 
-export function createHttpCommandTransport(options: HttpTransportOptions): CommandTransport {
+export function createHttpCommandTransport(options: HttpTransportOptions): CommandTransport<AnyCommandEnvelope> {
   const fetch = options.fetch ?? globalThis.fetch;
   let end = options.baseUrl.length;
   while (end > 0 && options.baseUrl[end - 1] === '/') {
@@ -53,11 +53,12 @@ export function createHttpCommandTransport(options: HttpTransportOptions): Comma
         try {
           body = await response.json();
         } catch {
-          return retry(controller.signal.aborted ? 'network' : 'bad_body');
+          return retry(controller.signal.aborted ? 'timeout' : 'bad_body');
         }
         return isCommandBatchResponse(body) ? { kind: 'results', results: body.results } : retry('bad_body');
       } catch {
-        return { kind: 'retry', reason: 'network' };
+        // `timeout`: sent, but no answer within the deadline. `network`: the store could not be reached.
+        return { kind: 'retry', reason: controller.signal.aborted ? 'timeout' : 'network' };
       } finally {
         clearTimeout(timeout);
       }

package/src/outbox/index.ts

@@ -2,6 +2,8 @@ export { createHttpCommandTransport } from './http-transport';
 export type { HttpTransportOptions } from './http-transport';
 export { createOrderOutbox } from './order-outbox';
 export type { OrderOutboxOptions, OrderOutbox } from './order-outbox';
+export { createRegisterOutbox } from './register-outbox';
+export type { RegisterOutboxOptions, RegisterOutbox } from './register-outbox';
 export type { TransportOutcome, CommandTransport, OutboxState } from './types';
 export { useOrderOutbox, outboxLogger } from './use-order-outbox';
 export type { UseOrderOutboxOptions, UseOrderOutboxResult } from './use-order-outbox';

package/src/outbox/logger.ts

@@ -0,0 +1,3 @@
+import { createLogger } from '../logging';
+
+export const outboxLogger = createLogger('outbox');