@tallyui/pos 3.0.4 → 3.1.1

package/dist/index.d.ts

@@ -465,6 +465,12 @@ interface OrderManager {
 }
 declare function createOrderManager(options: OrderManagerOptions): OrderManager;
 
+/** The parked sales in `drafts`, newest first, live; and a discard that removes one. */
+declare function useParkedSales(drafts: RxCollection | undefined): {
+    parked: ParkedOrderSummary[];
+    discard: (id: string) => Promise<void>;
+};
+
 interface ReceiptLineItem {
     name: string;
     sku: string;
@@ -596,6 +602,8 @@ interface PosOrderPayment {
 }
 interface PosOrder {
     id: string;
+    /** The sale order's id (the builder's), set by finalizeOrder (pos_orders v7, ADR-072): support traceability from a draft or preview to this stored order. Never sent, never printed. */
+    saleId?: string;
     createdAt: string;
     currency: string;
     pricesIncludeTax: boolean;
@@ -711,6 +719,8 @@ declare function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attemp
  * Like version 4 (ADR-069), it is one-way: an older build shows no orders.
  * Version 6 adds `taxRounding`, the strategy the sale's figures were computed with (#287; never sent), and changes
  * 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.
  */
 declare const posOrderSchema: RxJsonSchema<PosOrder>;
 /**
@@ -1895,6 +1905,14 @@ declare function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
         amountMinor: number;
         reference?: string;
     } | null) => void;
+    /** ADR-072: external is capped at the balance due; change comes only from cash. */
+    addTender(tender: {
+        method: "cash" | "external";
+        amountMinor: number;
+        reference?: string;
+    }): string | null;
+    /** ADR-072: remove one tender and its dropped-reference warning. An id not among the payments changes nothing. */
+    removeTender(paymentId: string): void;
     cancelTender(): void;
     /**
      * Finalizes the tender, stamps the session (see `session`), hands the order to `onSaleCompleted`,
@@ -2304,4 +2322,4 @@ declare function planLegs(plan: TenderPlan, rowsSinceFrom: {
     };
 };
 
-export { type Actor, type AddLineInput, type AppliedDiscount, type BackendNotFound, type BasketLine, CartError, type CashMovement, type CashMovementCollection, type CatalogueEntry, type Closure, type ClosureCollection, type ClosureContext, type ClosureScope, type CommandTransport, type Correction, CurrencyProvider, type CurrencyProviderProps, type CustomerSummary, DISCOUNTS_UNSUPPORTED, type Discount, type DisplayLine, type DisplayTotals, type FinalizeOptions, type HttpTransportOptions, type LedgerRow, type LineItem, type LineTaxLine, type LogEntry, type LogLevel, type LogSink, type Logger, MAX_TENDER_MINOR, MICROS_PER_MINOR, type Movement$1 as Movement, type MovementType, type Order, type OrderBuilder, type OrderBuilderOptions, OrderContentMismatchError, type OrderManager, type OrderManagerOptions, type OrderOutbox, type OrderOutboxOptions, type OrderTaxTotals, type OutboxState, type ParkedOrderSummary, type Payment, type PaymentMethod, type PaymentTransport, type PlanLeg, type PosOrder, type PosOrderLine, type PosOrderLocalWarning, PosOrderOpenClosedError, type PosOrderPayment, type PosOrderServerFailures, type PosOrderSyncStatus, type RateTaxLine, type ReceiptConfig, type ReceiptData, type ReceiptLineItem, type RecordedFigures, RegisterApprovalRequiredError, type RegisterBucket, RegisterCloseIncompleteError, type RegisterCommand, type RegisterCommandCollection, type RegisterCounters, type RegisterDocument, type RegisterFact, type RegisterHost, RegisterIdInvalidError, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, type RegisterOutbox, type RegisterOutboxOptions, type RegisterSession, RegisterSessionAlreadyOpenError, RegisterSessionClosedError, type RegisterSessionCollection, RegisterSessionRequiredError, type RegisterStore, RegisterTenderInProgressError, type Repository, type ResolveStoreSettingsOptions, SALE_SAVING, type SaleStage, type SentOrder, type SplitTab, type StoreSettingsResolution, type StoreSettingsState, TAX_ROUNDING_MIXED_NOTE, type TaxContext, type TaxLineInput, TaxProvider, type TaxProviderProps, type TaxRateMap, type TenderAction, type TenderKey, type TenderLineId, type TenderPlan, type TenderState, type TenderView, type TransportOutcome, UnsupportedOrderVersionError, type UseOrderOutboxOptions, type UseOrderOutboxResult, type UseRegisterOutboxOptions, type UseRegisterOutboxResult, type UseRegisterSessionOptions, activePlan, addEntryToCart, addPosOrderCollection, advancePerpetual, allocateOrderDiscount, appliedMinor, backToSelling, bindRegister, buildClosureDocument, buildReceiptData, buildXReportDocument, callbackSink, cashMovementSchema, catalogueEntries, changeMinor, clampClosureScope, closeNeedsApproval, closeSession, closureCommand, closureSchema, computeOrderTax, consoleSink, countVariance, createBackendNotFound, createHttpCommandTransport, createLogger, createOrderBuilder, createOrderManager, createOrderOutbox, createRegisterOutbox, createRepository, denominationTotal, denominations, deriveExpected, deriveSettled, ensureRegister, evenSplitShareMinor, exportCsv, finalizeOrder, findEntryByCode, formatClosureDate, getBoundRegisterId, getDeviceId, initTenderState, initialTenderState, isServerDecimal, labelKeys, minorToDecimal, mintClosureNumber, mintUuid, movementCommand, movementFieldError, needsAttention, nextSaleCounter, normalizeAmount, observeRegister$, openSession, openSessionSelector, orderDraftSchema, outboxLogger, overThreshold, parkedOrderSummaries$, parseMinor, planLegs, posOrderCollection, posOrderSchema, posOrdersLogger, quickTenderedAmounts, ratePpmFromPercent, readBoundRegister, readRegister, reconcileRegisterCommands, recordMovement, recordRegisterFact, registerCommandCollection, registerCommandSchema, registerCommandsLogger, registerFactsLogger, registerSessionCollection, registerSessionSchema, requireOpenSession, resolveStoreSettings, restoreOrderDraft, roundMicrosToMinor, saleLogger, sameSale, searchProducts, selectClosureRows, sessionOpenCommand, sessionTransitionCommand, stampSession, startCounting, stockOverlay$, stockOverlayAsOf$, taxFiguresForBasket, taxLinesByRate, taxLogger, taxMicros, taxProviderProps, tenderReducer, toOrderCreateEnvelope, unbindRegister, useCurrencyCode, useCurrencyFormatter, useOrderOutbox, useRegisterOutbox, useRegisterSession, useSale, useStoreSettings, useTax, uuidv7, validAmount, varianceText, variantPriceLabel, voidMovement, withPricingContext, writeClosure, writeOrderDraft };
+export { type Actor, type AddLineInput, type AppliedDiscount, type BackendNotFound, type BasketLine, CartError, type CashMovement, type CashMovementCollection, type CatalogueEntry, type Closure, type ClosureCollection, type ClosureContext, type ClosureScope, type CommandTransport, type Correction, CurrencyProvider, type CurrencyProviderProps, type CustomerSummary, DISCOUNTS_UNSUPPORTED, type Discount, type DisplayLine, type DisplayTotals, type FinalizeOptions, type HttpTransportOptions, type LedgerRow, type LineItem, type LineTaxLine, type LogEntry, type LogLevel, type LogSink, type Logger, MAX_TENDER_MINOR, MICROS_PER_MINOR, type Movement$1 as Movement, type MovementType, type Order, type OrderBuilder, type OrderBuilderOptions, OrderContentMismatchError, type OrderManager, type OrderManagerOptions, type OrderOutbox, type OrderOutboxOptions, type OrderTaxTotals, type OutboxState, type ParkedOrderSummary, type Payment, type PaymentMethod, type PaymentTransport, type PlanLeg, type PosOrder, type PosOrderLine, type PosOrderLocalWarning, PosOrderOpenClosedError, type PosOrderPayment, type PosOrderServerFailures, type PosOrderSyncStatus, type RateTaxLine, type ReceiptConfig, type ReceiptData, type ReceiptLineItem, type RecordedFigures, RegisterApprovalRequiredError, type RegisterBucket, RegisterCloseIncompleteError, type RegisterCommand, type RegisterCommandCollection, type RegisterCounters, type RegisterDocument, type RegisterFact, type RegisterHost, RegisterIdInvalidError, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, type RegisterOutbox, type RegisterOutboxOptions, type RegisterSession, RegisterSessionAlreadyOpenError, RegisterSessionClosedError, type RegisterSessionCollection, RegisterSessionRequiredError, type RegisterStore, RegisterTenderInProgressError, type Repository, type ResolveStoreSettingsOptions, SALE_SAVING, type SaleStage, type SentOrder, type SplitTab, type StoreSettingsResolution, type StoreSettingsState, TAX_ROUNDING_MIXED_NOTE, type TaxContext, type TaxLineInput, TaxProvider, type TaxProviderProps, type TaxRateMap, type TenderAction, type TenderKey, type TenderLineId, type TenderPlan, type TenderState, type TenderView, type TransportOutcome, UnsupportedOrderVersionError, type UseOrderOutboxOptions, type UseOrderOutboxResult, type UseRegisterOutboxOptions, type UseRegisterOutboxResult, type UseRegisterSessionOptions, activePlan, addEntryToCart, addPosOrderCollection, advancePerpetual, allocateOrderDiscount, appliedMinor, backToSelling, bindRegister, buildClosureDocument, buildReceiptData, buildXReportDocument, callbackSink, cashMovementSchema, catalogueEntries, changeMinor, clampClosureScope, closeNeedsApproval, closeSession, closureCommand, closureSchema, computeOrderTax, consoleSink, countVariance, createBackendNotFound, createHttpCommandTransport, createLogger, createOrderBuilder, createOrderManager, createOrderOutbox, createRegisterOutbox, createRepository, denominationTotal, denominations, deriveExpected, deriveSettled, ensureRegister, evenSplitShareMinor, exportCsv, finalizeOrder, findEntryByCode, formatClosureDate, getBoundRegisterId, getDeviceId, initTenderState, initialTenderState, isServerDecimal, labelKeys, minorToDecimal, mintClosureNumber, mintUuid, movementCommand, movementFieldError, needsAttention, nextSaleCounter, normalizeAmount, observeRegister$, openSession, openSessionSelector, orderDraftSchema, outboxLogger, overThreshold, parkedOrderSummaries$, parseMinor, planLegs, posOrderCollection, posOrderSchema, posOrdersLogger, quickTenderedAmounts, ratePpmFromPercent, readBoundRegister, readRegister, reconcileRegisterCommands, recordMovement, recordRegisterFact, registerCommandCollection, registerCommandSchema, registerCommandsLogger, registerFactsLogger, registerSessionCollection, registerSessionSchema, requireOpenSession, resolveStoreSettings, restoreOrderDraft, roundMicrosToMinor, saleLogger, sameSale, searchProducts, selectClosureRows, sessionOpenCommand, sessionTransitionCommand, stampSession, startCounting, stockOverlay$, stockOverlayAsOf$, taxFiguresForBasket, taxLinesByRate, taxLogger, taxMicros, taxProviderProps, tenderReducer, toOrderCreateEnvelope, unbindRegister, useCurrencyCode, useCurrencyFormatter, useOrderOutbox, useParkedSales, useRegisterOutbox, useRegisterSession, useSale, useStoreSettings, useTax, uuidv7, validAmount, varianceText, variantPriceLabel, voidMovement, withPricingContext, writeClosure, writeOrderDraft };

package/dist/index.js

@@ -1082,6 +1082,27 @@ function createOrderManager(options) {
   };
 }
 
+// src/order/use-parked-sales.ts
+import { useEffect as useEffect2, useState as useState2 } from "react";
+function useParkedSales(drafts) {
+  const [parked, setParked] = useState2([]);
+  useEffect2(() => {
+    if (!drafts) {
+      setParked([]);
+      return;
+    }
+    const subscription = parkedOrderSummaries$(drafts).subscribe((summaries) => {
+      setParked([...summaries].sort((a, b) => b.parkedAt.localeCompare(a.parkedAt)));
+    });
+    return () => subscription.unsubscribe();
+  }, [drafts]);
+  const discard = async (id2) => {
+    if (!drafts) throw new Error("useParkedSales: discard() needs the drafts collection");
+    await (await drafts.findOne(id2).exec())?.remove();
+  };
+  return { parked, discard };
+}
+
 // src/receipt/build-receipt-data.ts
 function buildReceiptData(order, config) {
   const taxLines = taxLinesByRate(order.lineItems, order.taxMinor, config.taxLabels, order.taxRounding).map(
@@ -1181,7 +1202,7 @@ function stockOverlayAsOf$(collection) {
 }
 
 // src/sale/use-sale.ts
-import { useEffect as useEffect3, useLayoutEffect, useRef as useRef3, useState as useState3 } from "react";
+import { useEffect as useEffect4, useLayoutEffect, useRef as useRef3, useState as useState4 } from "react";
 
 // src/pos-order/uuidv7.ts
 function format(ms, bytes) {
@@ -1418,6 +1439,7 @@ function finalizeOrder(order, options = {}) {
   const now = (options.now ?? /* @__PURE__ */ new Date()).toISOString();
   return freezeSentForm({
     id: id2,
+    saleId: order.id,
     createdAt: now,
     updatedAt: now,
     commandId: newId(),
@@ -1448,12 +1470,13 @@ function finalizeOrder(order, options = {}) {
 import { addRxPlugin } from "rxdb";
 import { RxDBMigrationSchemaPlugin } from "rxdb/plugins/migration-schema";
 var posOrderSchema = {
-  version: 6,
+  version: 7,
   primaryKey: "id",
   type: "object",
   additionalProperties: false,
   properties: {
     id: { type: "string", maxLength: 36 },
+    saleId: { type: "string", maxLength: 36 },
     commandId: { type: "string", maxLength: 36 },
     createdAt: { type: "string", maxLength: 40 },
     updatedAt: { type: "string" },
@@ -1602,7 +1625,7 @@ function posOrderCollection() {
   };
   return {
     schema: posOrderSchema,
-    migrationStrategies: { 1: identity2, 2: identity2, 3: identity2, 4: identity2, 5: recordSent, 6: recordRounding }
+    migrationStrategies: { 1: identity2, 2: identity2, 3: identity2, 4: identity2, 5: recordSent, 6: recordRounding, 7: identity2 }
   };
 }
 
@@ -2994,7 +3017,7 @@ function buildXReportDocument(session, context) {
 }
 
 // src/register/use-register-session.ts
-import { useEffect as useEffect2, useMemo as useMemo3, useRef as useRef2, useState as useState2, useSyncExternalStore } from "react";
+import { useEffect as useEffect3, useMemo as useMemo3, useRef as useRef2, useState as useState3, useSyncExternalStore } from "react";
 import { combineLatest, map as map5, of, switchMap } from "rxjs";
 
 // src/register/register-commands.ts
@@ -3214,7 +3237,7 @@ function useRegisterSession(options) {
       }
     });
   };
-  useEffect2(reconcile, [commandTarget]);
+  useEffect3(reconcile, [commandTarget]);
   const source = useMemo3(() => {
     if (!enabled || !sessions || !movements || !closures || !orders || !registerId || !register) return null;
     return combineLatest([
@@ -3233,14 +3256,14 @@ function useRegisterSession(options) {
   const tender = useRef2(tenderInProgress);
   tender.current = tenderInProgress;
   const closing = useSyncExternalStore(subscribeClosing, () => closingByRegister.has(registerId ?? ""));
-  const [observed, setObserved] = useState2(null);
-  useEffect2(() => {
+  const [observed, setObserved] = useState3(null);
+  useEffect3(() => {
     if (!source) return;
     const subscription = source.subscribe((snapshot) => setObserved({ source, snapshot }));
     return () => subscription.unsubscribe();
   }, [source]);
-  const [, setMinute] = useState2(0);
-  useEffect2(() => {
+  const [, setMinute] = useState3(0);
+  useEffect3(() => {
     if (!enabled || !expectedCloseTime) return;
     const timer = setInterval(() => setMinute((value) => value + 1), 6e4);
     return () => clearInterval(timer);
@@ -3272,7 +3295,7 @@ function useRegisterSession(options) {
     return state.running = run;
   };
   const seen = useRef2(null);
-  useEffect2(() => {
+  useEffect3(() => {
     if (!data) return;
     const ids = data.closureRows.map((row) => row.id);
     if (seen.current?.source !== source) {
@@ -3545,19 +3568,19 @@ var HUNG_SAVE_CHECK_MS = 5e3;
 function useSale(settings, opts) {
   const taxContext = useTax();
   const madeWith = useRef3({ taxContext, currency: settings.currency });
-  const [rendered, setBuilder] = useState3(() => createOrderBuilder({ currency: settings.currency, taxContext }));
+  const [rendered, setBuilder] = useState4(() => createOrderBuilder({ currency: settings.currency, taxContext }));
   const builderNow = useRef3(rendered);
-  const [order, setOrder] = useState3(() => rendered.getSnapshot());
-  const [stage, setStage] = useState3({ kind: "cart" });
-  const [saleError, setError] = useState3(null);
+  const [order, setOrder] = useState4(() => rendered.getSnapshot());
+  const [stage, setStage] = useState4({ kind: "cart" });
+  const [saleError, setError] = useState4(null);
   const configError = referenceError("cashierRef", opts.cashierRef) ?? referenceError("registerId", opts.registerId);
   const pending = useRef3(null);
-  const [saving, setSaving] = useState3(false);
+  const [saving, setSaving] = useState4(false);
   const error = saving && saleError ? saleError : configError ?? saleError;
   const tenderSession = useRef3(null);
-  const droppedReference = useRef3(null);
+  const droppedReferences = useRef3(/* @__PURE__ */ new Set());
   const confirmed = useRef3(null);
-  const [canContinue, setCanContinue] = useState3(false);
+  const [canContinue, setCanContinue] = useState4(false);
   const attempts = useRef3(0);
   const hungSaveTimer = useRef3(null);
   const checking = useRef3(null);
@@ -3590,7 +3613,7 @@ function useSale(settings, opts) {
     pending.current = null;
     inFlight.current = null;
     tenderSession.current = null;
-    droppedReference.current = null;
+    droppedReferences.current.clear();
     setSaving(false);
     madeWith.current = { taxContext, currency: settings.currency };
     const next = restored ?? createOrderBuilder({ currency: settings.currency, taxContext });
@@ -3601,7 +3624,7 @@ function useSale(settings, opts) {
     setStage({ kind: "cart" });
     setError(null);
   }
-  useEffect3(() => {
+  useEffect4(() => {
     const subscription = rendered.order$.subscribe(setOrder);
     return () => subscription.unsubscribe();
   }, [rendered]);
@@ -3611,7 +3634,7 @@ function useSale(settings, opts) {
     const liveIdle = stageNow.current.kind === "cart" && !live.lineItems.length && !inFlight.current && !pending.current;
     if (liveIdle && (madeWith.current.taxContext !== taxContext || madeWith.current.currency !== settings.currency)) resetSale(live.customer ?? null);
   });
-  useEffect3(() => () => {
+  useEffect4(() => () => {
     clearHungSaveTimer();
     if (pending.current || inFlight.current) {
       saleLogger.error(
@@ -3620,21 +3643,29 @@ function useSale(settings, opts) {
       );
     }
   }, []);
-  function setTender(tender) {
-    if (locked()) return;
-    const reason = referenceReason(tender?.reference);
+  function addOne(tender) {
+    const reason = referenceReason(tender.reference);
     const dropped = reason && (reason === "nul" ? "it contains a NUL character" : `it is over ${PAYLOAD_STRING_MAX} characters`);
-    const kept = tender && dropped ? { method: tender.method, amountMinor: tender.amountMinor } : tender;
+    const kept = dropped ? { method: tender.method, amountMinor: tender.amountMinor } : tender;
     const builder = builderNow.current;
-    const previous = builder.getSnapshot().payments[0];
-    if (previous) builder.removePayment(previous.id);
-    const paymentId = kept ? builder.addPayment(kept) : null;
-    droppedReference.current = dropped ? paymentId : null;
-    setError(dropped && `The terminal's payment reference couldn't be kept (${dropped}); the payment is recorded without it.`);
+    const paymentId = builder.addPayment(kept);
+    if (dropped) {
+      droppedReferences.current.add(paymentId);
+      setError(`The terminal's payment reference couldn't be kept (${dropped}); the payment is recorded without it.`);
+    }
     try {
       if (dropped) saleLogger.warn("the terminal's payment reference was dropped", { reason: dropped, method: tender.method });
     } catch {
     }
+    return paymentId;
+  }
+  function setTender(tender) {
+    if (locked()) return;
+    const builder = builderNow.current;
+    for (const payment of builder.getSnapshot().payments) builder.removePayment(payment.id);
+    droppedReferences.current.clear();
+    setError(null);
+    if (tender) addOne(tender);
   }
   function checkStored(completion) {
     const attempt2 = attempts.current;
@@ -3672,7 +3703,7 @@ function useSale(settings, opts) {
     if (hungSaveTimer.current === timer) clearHungSaveTimer();
     if (pending.current !== completion) return;
     pending.current = null;
-    droppedReference.current = null;
+    droppedReferences.current.clear();
     confirm(null);
     setSaving(false);
     setError(null);
@@ -3778,6 +3809,23 @@ function useSale(settings, opts) {
       setStage({ kind: "tender", method });
     },
     setTender,
+    /** ADR-072: external is capped at the balance due; change comes only from cash. */
+    addTender(tender) {
+      if (locked() || !Number.isInteger(tender.amountMinor) || tender.amountMinor <= 0) return null;
+      if (tender.method === "external") {
+        const due = builderNow.current.getSnapshot().balanceDueMinor;
+        if (due <= 0) return null;
+        return addOne({ ...tender, amountMinor: Math.min(tender.amountMinor, due) });
+      }
+      return addOne(tender);
+    },
+    /** ADR-072: remove one tender and its dropped-reference warning. An id not among the payments changes nothing. */
+    removeTender(paymentId) {
+      if (locked()) return;
+      if (!builderNow.current.getSnapshot().payments.some((payment) => payment.id === paymentId)) return;
+      builderNow.current.removePayment(paymentId);
+      droppedReferences.current.delete(paymentId);
+    },
     cancelTender() {
       if (locked()) return;
       setTender(null);
@@ -3805,13 +3853,14 @@ function useSale(settings, opts) {
       if (pending.current) return deliver(pending.current);
       setSaving(true);
       const current = builderNow.current.getSnapshot();
+      const localWarnings = current.payments.filter((payment) => droppedReferences.current.has(payment.id)).map((payment) => ({ code: "payment_reference_dropped", paymentId: payment.id }));
       let posOrder;
       try {
         posOrder = finalizeOrder(current, {
           registerId: opts.registerId,
           cashierRef: opts.cashierRef,
           capabilities: opts.capabilities,
-          ...droppedReference.current ? { localWarnings: [{ code: "payment_reference_dropped", paymentId: droppedReference.current }] } : {}
+          ...localWarnings.length ? { localWarnings } : {}
         });
       } catch (error2) {
         setSaving(false);
@@ -4735,15 +4784,15 @@ function createRegisterOutbox(options) {
 }
 
 // src/outbox/use-register-outbox.ts
-import { useEffect as useEffect4, useRef as useRef4, useState as useState4 } from "react";
+import { useEffect as useEffect5, useRef as useRef4, useState as useState5 } from "react";
 var idle = { pending: 0, sending: false };
 function useRegisterOutbox(options) {
   const { commands, deviceId } = options;
   const latest = useRef4(options);
   latest.current = options;
   const current = useRef4(null);
-  const [state, setState] = useState4(idle);
-  useEffect4(() => {
+  const [state, setState] = useState5(idle);
+  useEffect5(() => {
     setState(idle);
     if (!commands) return;
     const outbox = createRegisterOutbox({
@@ -4777,7 +4826,7 @@ function useRegisterOutbox(options) {
 }
 
 // src/outbox/use-order-outbox.ts
-import { useEffect as useEffect5, useMemo as useMemo4, useRef as useRef5, useState as useState5 } from "react";
+import { useEffect as useEffect6, useMemo as useMemo4, useRef as useRef5, useState as useState6 } from "react";
 var idle2 = { pending: 0, sending: false };
 var noneStuck = [];
 function useOrderOutbox(options) {
@@ -4787,12 +4836,12 @@ function useOrderOutbox(options) {
   const current = useRef5(null);
   const openingError = useRef5(null);
   const loggedMismatches = useRef5(/* @__PURE__ */ new Set());
-  const [orders, setOrders] = useState5(null);
-  const [state, setState] = useState5(idle2);
-  const [recent, setRecent] = useState5([]);
+  const [orders, setOrders] = useState6(null);
+  const [state, setState] = useState6(idle2);
+  const [recent, setRecent] = useState6([]);
   const savesInFlight = useRef5(0);
-  const [savesInFlightCount, setSavesInFlightCount] = useState5(0);
-  useEffect5(() => {
+  const [savesInFlightCount, setSavesInFlightCount] = useState6(0);
+  useEffect6(() => {
     let active = true;
     let dispose;
     openingError.current = null;
@@ -4835,7 +4884,7 @@ function useOrderOutbox(options) {
       dispose?.();
     };
   }, [storeKey, deviceId]);
-  useEffect5(() => {
+  useEffect6(() => {
     latest.current.onBusy?.(state.sending);
     return () => latest.current.onBusy?.(false);
   }, [state.sending]);
@@ -5218,6 +5267,7 @@ export {
   useCurrencyCode,
   useCurrencyFormatter,
   useOrderOutbox,
+  useParkedSales,
   useRegisterOutbox,
   useRegisterSession,
   useSale,

package/package.json

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

package/src/index.ts

@@ -27,6 +27,7 @@ export type { Repository } from './repository';
 // Order
 export { createOrderBuilder, createOrderManager, allocateOrderDiscount, taxFiguresForBasket } from './order';
 export { orderDraftSchema, writeOrderDraft, restoreOrderDraft, parkedOrderSummaries$ } from './order';
+export { useParkedSales } from './order';
 export type { BasketLine } from './order';
 export type { OrderBuilder, OrderBuilderOptions } from './order';
 export type { OrderManager, OrderManagerOptions, ParkedOrderSummary } from './order';

package/src/order/index.ts

@@ -5,6 +5,7 @@ export { allocateOrderDiscount } from './allocate-order-discount';
 export type { OrderBuilder, OrderBuilderOptions } from './order-builder';
 export { createOrderManager } from './order-manager';
 export { orderDraftSchema, writeOrderDraft, restoreOrderDraft, parkedOrderSummaries$ } from './order-drafts';
+export { useParkedSales } from './use-parked-sales';
 export type { OrderManager, OrderManagerOptions, ParkedOrderSummary } from './order-manager';
 export type {
   Order,

package/src/order/use-parked-sales.ts

@@ -0,0 +1,24 @@
+import { useEffect, useState } from 'react';
+import type { RxCollection } from 'rxdb';
+import { parkedOrderSummaries$, type ParkedOrderSummary } from './order-drafts';
+
+/** The parked sales in `drafts`, newest first, live; and a discard that removes one. */
+export function useParkedSales(drafts: RxCollection | undefined): {
+  parked: ParkedOrderSummary[];
+  discard: (id: string) => Promise<void>;
+} {
+  const [parked, setParked] = useState<ParkedOrderSummary[]>([]);
+  useEffect(() => {
+    if (!drafts) { setParked([]); return; }
+    const subscription = parkedOrderSummaries$(drafts).subscribe((summaries) => {
+      setParked([...summaries].sort((a, b) => b.parkedAt.localeCompare(a.parkedAt)));
+    });
+    return () => subscription.unsubscribe();
+  }, [drafts]);
+
+  const discard = async (id: string): Promise<void> => {
+    if (!drafts) throw new Error('useParkedSales: discard() needs the drafts collection');
+    await (await drafts.findOne(id).exec())?.remove();
+  };
+  return { parked, discard };
+}

package/src/pos-order/finalize.ts

@@ -204,7 +204,7 @@ export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosO
     : { granularity: rounding.granularity, mode: rounding.mode };
   const now = (options.now ?? new Date()).toISOString();
   return freezeSentForm({
-    id, createdAt: now, updatedAt: now, commandId: newId(), syncStatus: 'pending',
+    id, saleId: order.id, createdAt: now, updatedAt: now, commandId: newId(), syncStatus: 'pending',
     currency: order.currency, pricesIncludeTax: order.pricesIncludeTax, lines, payments,
     subtotalMinor: order.subtotalMinor, discountMinor: order.discountMinor,
     taxMinor: order.taxMinor, totalMinor: order.totalMinor, taxRounding,

package/src/pos-order/schema.ts

@@ -18,11 +18,14 @@ import type { PosOrder } from './types';
  * Like version 4 (ADR-069), it is one-way: an older build shows no orders.
  * Version 6 adds `taxRounding`, the strategy the sale's figures were computed with (#287; never sent), and changes
  * 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.
  */
 export const posOrderSchema: RxJsonSchema<PosOrder> = {
-  version: 6, primaryKey: 'id', type: 'object', additionalProperties: false,
+  version: 7, primaryKey: 'id', type: 'object', additionalProperties: false,
   properties: {
     id: { type: 'string', maxLength: 36 },
+    saleId: { type: 'string', maxLength: 36 },
     commandId: { type: 'string', maxLength: 36 },
     createdAt: { type: 'string', maxLength: 40 },
     updatedAt: { type: 'string' },
@@ -126,5 +129,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 } };
+    migrationStrategies: { 1: identity, 2: identity, 3: identity, 4: identity, 5: recordSent, 6: recordRounding, 7: identity } };
 }

package/src/pos-order/types.ts

@@ -42,6 +42,8 @@ export interface PosOrderPayment {
 
 export interface PosOrder {
   id: string;
+  /** The sale order's id (the builder's), set by finalizeOrder (pos_orders v7, ADR-072): support traceability from a draft or preview to this stored order. Never sent, never printed. */
+  saleId?: string;
   createdAt: string;
   currency: string;
   pricesIncludeTax: boolean;

package/src/sale/use-sale.ts

@@ -72,8 +72,8 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
   const error = saving && saleError ? saleError : configError ?? saleError;
   // The session pinned by startTender for this tender (`undefined` inside: none); null until a tender starts.
   const tenderSession = useRef<{ session: typeof opts.session } | null>(null);
-  // The id, at the tender, of the payment whose terminal reference setTender dropped; null when none was dropped.
-  const droppedReference = useRef<string | null>(null);
+  // The ids, at the tender, of payments whose terminal references were dropped.
+  const droppedReferences = useRef<Set<string>>(new Set());
   // The pending completion isStored confirmed stored after its save failed; `canContinue` mirrors it for
   // rendering. `attempts` counts complete() attempts, so a confirmation that lands after a new one is dropped.
   const confirmed = useRef<{ order: Order; posOrder: PosOrder } | null>(null);
@@ -115,7 +115,7 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
     confirm(null); pending.current = null;
     inFlight.current = null;
     tenderSession.current = null;
-    droppedReference.current = null;
+    droppedReferences.current.clear();
     setSaving(false);
     madeWith.current = { taxContext, currency: settings.currency };
     const next = restored ?? createOrderBuilder({ currency: settings.currency, taxContext });
@@ -149,23 +149,32 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
     }
   }, []);
 
-  function setTender(tender: { method: 'cash' | 'external'; amountMinor: number; reference?: string } | null) {
-    if (locked()) return;
+  function addOne(tender: { method: 'cash' | 'external'; amountMinor: number; reference?: string }): string {
     // A terminal reference finalize would refuse is dropped as it's entered, never the payment (the money is
     // taken): the tender applies without it, with a message that doesn't block complete() and a
     // localWarnings entry on the stored order naming the payment whose reference was dropped.
-    const reason = referenceReason(tender?.reference);
+    const reason = referenceReason(tender.reference);
     const dropped = reason && (reason === 'nul' ? 'it contains a NUL character' : `it is over ${PAYLOAD_STRING_MAX} characters`);
-    const kept = tender && dropped ? { method: tender.method, amountMinor: tender.amountMinor } : tender;
+    const kept = dropped ? { method: tender.method, amountMinor: tender.amountMinor } : tender;
     const builder = builderNow.current;
-    const previous = builder.getSnapshot().payments[0];
-    if (previous) builder.removePayment(previous.id);
-    const paymentId = kept ? builder.addPayment(kept) : null;
-    droppedReference.current = dropped ? paymentId : null;
-    setError(dropped && `The terminal's payment reference couldn't be kept (${dropped}); the payment is recorded without it.`);
+    const paymentId = builder.addPayment(kept);
+    if (dropped) {
+      droppedReferences.current.add(paymentId);
+      setError(`The terminal's payment reference couldn't be kept (${dropped}); the payment is recorded without it.`);
+    }
     try {
-      if (dropped) saleLogger.warn("the terminal's payment reference was dropped", { reason: dropped, method: tender!.method });
+      if (dropped) saleLogger.warn("the terminal's payment reference was dropped", { reason: dropped, method: tender.method });
     } catch { /* a failing sink must never lose the tender */ }
+    return paymentId;
+  }
+
+  function setTender(tender: { method: 'cash' | 'external'; amountMinor: number; reference?: string } | null) {
+    if (locked()) return;
+    const builder = builderNow.current;
+    for (const payment of builder.getSnapshot().payments) builder.removePayment(payment.id);
+    droppedReferences.current.clear();
+    setError(null);
+    if (tender) addOne(tender);
   }
 
   /** Asks `isStored`; Continue is offered only once it confirms, for this attempt, with the completion still pending. */
@@ -212,7 +221,7 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
     if (hungSaveTimer.current === timer) clearHungSaveTimer();
     if (pending.current !== completion) return;
     pending.current = null;
-    droppedReference.current = null;
+    droppedReferences.current.clear();
     confirm(null);
     setSaving(false);
     setError(null);
@@ -315,6 +324,23 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
       setStage({ kind: 'tender', method });
     },
     setTender,
+    /** ADR-072: external is capped at the balance due; change comes only from cash. */
+    addTender(tender: { method: 'cash' | 'external'; amountMinor: number; reference?: string }): string | null {
+      if (locked() || !Number.isInteger(tender.amountMinor) || tender.amountMinor <= 0) return null;
+      if (tender.method === 'external') {
+        const due = builderNow.current.getSnapshot().balanceDueMinor;
+        if (due <= 0) return null;
+        return addOne({ ...tender, amountMinor: Math.min(tender.amountMinor, due) });
+      }
+      return addOne(tender);
+    },
+    /** ADR-072: remove one tender and its dropped-reference warning. An id not among the payments changes nothing. */
+    removeTender(paymentId: string): void {
+      if (locked()) return;
+      if (!builderNow.current.getSnapshot().payments.some((payment) => payment.id === paymentId)) return;
+      builderNow.current.removePayment(paymentId);
+      droppedReferences.current.delete(paymentId);
+    },
     cancelTender() {
       if (locked()) return;
       setTender(null);
@@ -342,10 +368,12 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
       if (pending.current) return deliver(pending.current);
       setSaving(true);
       const current = builderNow.current.getSnapshot();
+      const localWarnings = current.payments.filter((payment) => droppedReferences.current.has(payment.id))
+        .map((payment) => ({ code: 'payment_reference_dropped' as const, paymentId: payment.id }));
       let posOrder: PosOrder;
       try {
         posOrder = finalizeOrder(current, { registerId: opts.registerId, cashierRef: opts.cashierRef, capabilities: opts.capabilities,
-          ...(droppedReference.current ? { localWarnings: [{ code: 'payment_reference_dropped', paymentId: droppedReference.current }] } : {}) });
+          ...(localWarnings.length ? { localWarnings } : {}) });
       } catch (error) {
         setSaving(false);
         setError((error as Error).message);