@tallyui/pos 3.0.0-next.0 → 3.0.0-next.2

package/dist/index.d.ts

@@ -177,7 +177,7 @@ declare function resolveStoreSettings(options: ResolveStoreSettingsOptions, choi
 /** The replication's context with the settings' opaque pricing context; the key is left out when the settings have none. */
 declare function withPricingContext(context: SyncContext, settings: StoreSettings): SyncContext;
 /**
- * `<TaxProvider>`'s props from the same settings, so its tax inclusivity and rounding match the store's. `custom`
+ * `<TaxProvider>`'s props from the same settings, so its tax inclusivity, rounding and rate codes match the store's. `custom`
  * rounding passes none, the default (#287). An explicit `rounding` prop after the spread still wins, since JSX
  * applies props in order; so `<TaxProvider {...taxProviderProps(s)} rounding={undefined}>` wipes the store's rounding.
  */
@@ -198,6 +198,7 @@ type StoreSettingsState = {
     state: 'error';
     error: unknown;
     retry: () => void;
+    nextRetryAt?: number;
 } | {
     state: 'unsupported';
 };
@@ -208,6 +209,10 @@ type StoreSettingsState = {
  * The ready settings carry the store's `taxRounding` from the capabilities, so `taxProviderProps` passes it on (#324).
  * The capabilities are read beside the settings, before `ready`, so each resolve emits the settings once, with the
  * rounding already known: no later change of `settings` holds a sale.
+ * Unknown rounding keeps settings unresolved and retries by itself; show "Can't reach the store's settings yet. Retrying…" while `nextRetryAt` is set.
+ * A till-class or invalid-credentials sign-in error is not retried by itself, so the app prompts to sign in or update the till.
+ * An app shows a sign-in prompt when the `error` state's error is a `ConnectorUnauthorizedError` with `code: 'unauthorized'`
+ * or a `SignInError` with `code: 'invalid_credentials'`, and an update prompt for `code: 'till_update_required'`.
  *
  * ```tsx
  * const store = useStoreSettings({ connector, context, loadChoice, saveChoice });
@@ -1948,14 +1953,18 @@ interface OutboxState {
     /** Set while the store (not offline) has kept failing some orders for 15 minutes, each on its own clock. Those
      * orders stay pending and keep retrying. `orders` has each order's own entry: its `since` is when its clock
      * would have started had there been no offline gaps (now minus its answered time; while offline, as of the
-     * moment the clock paused), and its latest `reason`. `since` is the earliest of theirs; `reason` the latest. */
+     * moment the clock paused), and its latest `reason`. `since` is the earliest of theirs, virtual for the threshold;
+     * `reason` the latest. `firstFailedAt` is the earliest real wall-clock first failure, only when every stuck clock
+     * has one. Each order entry has its own real wall-clock `firstFailedAt`. Both are in memory only, absent after restart. */
     stuck?: {
         commandIds: string[];
         since: number;
+        firstFailedAt?: number;
         reason: string;
         orders: {
             commandId: string;
             since: number;
+            firstFailedAt?: number;
             reason: string;
         }[];
     };
@@ -2041,6 +2050,27 @@ interface RegisterOutbox {
 }
 declare function createRegisterOutbox(options: RegisterOutboxOptions): RegisterOutbox;
 
+interface UseRegisterOutboxOptions {
+    /** `register_commands` (see `registerCommandCollection()`); `null` while it opens or when there's no store. A new collection (a store switch) restarts the outbox. */
+    commands: RegisterCommandCollection | null;
+    /** Builds the transport; called when the outbox is created: on each new collection or device id (twice under React StrictMode's double effect, which stops the first outbox). */
+    transport(): CommandTransport<RegisterCommandEnvelope>;
+    /** The device id sent on every command. A change restarts the outbox. */
+    deviceId: string;
+    /** Passed through to createRegisterOutbox (same meaning). The latest function is called each time, so a new one does not restart the outbox. */
+    isEnabled?: () => boolean;
+    /** Called with each result. The latest function is called each time; a new one does not restart the outbox. */
+    onResult?: RegisterOutboxOptions['onResult'];
+    backendNotFound?: RegisterOutboxOptions['backendNotFound'];
+}
+interface UseRegisterOutboxResult {
+    /** The outbox state, or idle ({ pending: 0, sending: false }) while there is no collection. */
+    state: OutboxState;
+    /** Sends pending till updates; does nothing while there is no collection. */
+    flush(): Promise<void>;
+}
+declare function useRegisterOutbox(options: UseRegisterOutboxOptions): UseRegisterOutboxResult;
+
 declare const outboxLogger: Logger;
 
 interface UseOrderOutboxOptions {
@@ -2247,4 +2277,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 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, outboxLogger, overThreshold, parseMinor, planLegs, posOrderCollection, posOrderSchema, posOrdersLogger, quickTenderedAmounts, ratePpmFromPercent, readBoundRegister, readRegister, reconcileRegisterCommands, recordMovement, recordRegisterFact, registerCommandCollection, registerCommandSchema, registerCommandsLogger, registerFactsLogger, registerSessionCollection, registerSessionSchema, requireOpenSession, resolveStoreSettings, roundMicrosToMinor, saleLogger, sameSale, searchProducts, selectClosureRows, sessionOpenCommand, sessionTransitionCommand, stampSession, startCounting, stockOverlay$, stockOverlayAsOf$, taxFiguresForBasket, taxLinesByRate, taxLogger, taxMicros, taxProviderProps, tenderReducer, toOrderCreateEnvelope, unbindRegister, useCurrencyCode, useCurrencyFormatter, useOrderOutbox, useRegisterSession, useSale, useStoreSettings, useTax, uuidv7, validAmount, varianceText, variantPriceLabel, voidMovement, withPricingContext, writeClosure };
+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, outboxLogger, overThreshold, parseMinor, planLegs, posOrderCollection, posOrderSchema, posOrdersLogger, quickTenderedAmounts, ratePpmFromPercent, readBoundRegister, readRegister, reconcileRegisterCommands, recordMovement, recordRegisterFact, registerCommandCollection, registerCommandSchema, registerCommandsLogger, registerFactsLogger, registerSessionCollection, registerSessionSchema, requireOpenSession, resolveStoreSettings, 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 };

package/dist/index.js

@@ -319,26 +319,47 @@ function withPricingContext(context, settings) {
 }
 function taxProviderProps(settings) {
   const rounding = settings.taxRounding?.granularity === "custom" ? void 0 : settings.taxRounding;
-  return { ratesPpm: settings.taxRatesPpm, pricesIncludeTax: settings.pricesIncludeTax, ...rounding && { rounding } };
+  return { ratesPpm: settings.taxRatesPpm, pricesIncludeTax: settings.pricesIncludeTax, ...rounding && { rounding }, ...settings.taxRateCodes && { rateCodes: settings.taxRateCodes } };
 }
 
 // src/store-settings/use-store-settings.ts
 import { useCallback as useCallback2, useEffect, useRef, useState } from "react";
+import { errorKind, SignInError } from "@tallyui/core";
 var LOADING = { state: "loading" };
+var StoreCapabilitiesUnavailableError = class extends Error {
+  constructor(cause) {
+    super("Store capabilities unavailable", { cause });
+    this.name = "StoreCapabilitiesUnavailableError";
+  }
+};
+var INITIAL_RETRY_MS = 5e3;
+var MAX_RETRY_MS = 5 * 6e4;
 function readTaxRounding({ connector, context }) {
   if (context.capabilities) return Promise.resolve(context.capabilities.taxRounding);
   if (!connector.storeSettings || !connector.capabilities) return Promise.resolve(void 0);
   const read = connector.capabilities;
-  return Promise.resolve().then(() => read(context)).then((capabilities) => capabilities?.taxRounding, () => void 0);
+  return Promise.resolve().then(() => read(context)).then(
+    (capabilities) => {
+      if (!capabilities) throw new StoreCapabilitiesUnavailableError();
+      return capabilities.taxRounding;
+    },
+    (cause) => {
+      if (errorKind(cause) === "till" || cause instanceof SignInError && cause.code === "invalid_credentials") throw cause;
+      throw new StoreCapabilitiesUnavailableError(cause);
+    }
+  );
 }
 function useStoreSettings(options) {
   const { connector, context } = options;
   const optionsRef = useRef(options);
   optionsRef.current = options;
   const requestRef = useRef(0);
+  const retryTimerRef = useRef(void 0);
+  const retryDelayRef = useRef(INITIAL_RETRY_MS);
   const [state, setState] = useState(LOADING);
   const resolve = useCallback2((choice, from, known) => {
     if (from !== void 0 && from !== requestRef.current) return;
+    clearTimeout(retryTimerRef.current);
     const request = ++requestRef.current;
     const current = () => request === requestRef.current;
     setState(LOADING);
@@ -346,6 +367,7 @@ function useStoreSettings(options) {
     Promise.all([resolveStoreSettings(optionsRef.current, choice), rounding]).then(
       ([result, taxRounding]) => {
         if (!current()) return;
+        retryDelayRef.current = INITIAL_RETRY_MS;
         if (result.status === "ready")
           setState({ state: "ready", settings: taxRounding ? { ...result.settings, taxRounding } : result.settings, choice: result.choice });
         else if (result.status === "choose")
@@ -354,13 +376,23 @@ function useStoreSettings(options) {
       },
       // A retry keeps the choice that failed: a new pick is saved only once it resolves.
       (error) => {
-        if (current()) setState({ state: "error", error, retry: () => resolve(choice, request) });
+        if (!current()) return;
+        const retry = () => resolve(choice, request);
+        if (error instanceof StoreCapabilitiesUnavailableError) {
+          const delay = retryDelayRef.current;
+          const nextRetryAt = Date.now() + delay;
+          retryDelayRef.current = Math.min(delay * 2, MAX_RETRY_MS);
+          retryTimerRef.current = setTimeout(retry, delay);
+          setState({ state: "error", error, retry, nextRetryAt });
+        } else setState({ state: "error", error, retry });
       }
     );
   }, []);
   useEffect(() => {
     resolve();
     return () => {
+      clearTimeout(retryTimerRef.current);
+      retryDelayRef.current = INITIAL_RETRY_MS;
       requestRef.current += 1;
     };
   }, [connector, context, resolve]);
@@ -3533,7 +3565,7 @@ function useSale(settings, opts) {
     const subscription = rendered.order$.subscribe(setOrder);
     return () => subscription.unsubscribe();
   }, [rendered]);
-  const idle2 = stage.kind === "cart" && !order.lineItems.length;
+  const idle3 = stage.kind === "cart" && !order.lineItems.length;
   useLayoutEffect(() => {
     const live = builderNow.current.getSnapshot();
     const liveIdle = stageNow.current.kind === "cart" && !live.lineItems.length && !inFlight.current && !pending.current;
@@ -3620,7 +3652,7 @@ function useSale(settings, opts) {
     order,
     stage,
     error,
-    idle: idle2,
+    idle: idle3,
     /** A completion is pending (see `complete()`): the sale is locked, and the UI offers Retry. */
     saving,
     /** The failed save's order is confirmed stored (see `isStored`): the UI also offers Continue (`continueSale()`). */
@@ -3940,8 +3972,14 @@ function createOrderOutbox(options) {
     return {
       commandIds: stuck.map(([id2]) => id2),
       since: Math.min(...stuck.map(([, clock]) => clock.since)),
+      ...stuck.every(([, clock]) => clock.firstFailedAt !== void 0) ? { firstFailedAt: Math.min(...stuck.map(([, clock]) => clock.firstFailedAt)) } : {},
       reason: stuck.reduce((latest, entry) => entry[1].seq > latest[1].seq ? entry : latest)[1].reason,
-      orders: stuck.map(([commandId, { since, reason }]) => ({ commandId, since, reason }))
+      orders: stuck.map(([commandId, { since, firstFailedAt, reason }]) => ({
+        commandId,
+        since,
+        reason,
+        ...firstFailedAt === void 0 ? {} : { firstFailedAt }
+      }))
     };
   }
   function isDue(id2) {
@@ -3980,6 +4018,7 @@ function createOrderOutbox(options) {
   }
   const bare = ({ serverFailures, _rev, _meta, ...data }) => data;
   const failuresOnly = (before, after) => !deepEqual2(before.serverFailures, after.serverFailures) && deepEqual2(bare(before), bare(after));
+  const recordsSentForm = (before, after) => deepEqual2(bare({ ...freezeSentForm(before), sentVersion: before.sentVersion ?? after.sentVersion }), bare(after));
   async function updateState(patch = {}) {
     const pending = await countFresh(collection, { syncStatus: "pending" });
     const rejected = await countFresh(collection, { syncStatus: "rejected" });
@@ -3992,7 +4031,7 @@ function createOrderOutbox(options) {
   }
   function serverFailed(orders, alone, reason, retryAfterMs) {
     const at2 = now();
-    for (const { commandId } of orders) clocks.set(commandId, { since: clocks.get(commandId)?.since ?? at2, seq: ++failureSeq, reason });
+    for (const { commandId } of orders) clocks.set(commandId, { ...clocks.get(commandId) ?? { since: at2, firstFailedAt: at2 }, seq: ++failureSeq, reason });
     const id2 = orders[0].commandId;
     if (alone === "isolated") {
       isolate(id2, reason, retryAfterMs);
@@ -4311,7 +4350,7 @@ function createOrderOutbox(options) {
       stopped = false;
       watchBackendMissing();
       if (!subscription) subscription = collection.$.subscribe((event) => {
-        if (event.documentData?.syncStatus === "pending" && (event.operation === "INSERT" || event.operation === "UPDATE" && !(event.previousDocumentData !== void 0 && failuresOnly(event.previousDocumentData, event.documentData)))) {
+        if (event.documentData?.syncStatus === "pending" && (event.operation === "INSERT" || event.operation === "UPDATE" && !(event.previousDocumentData !== void 0 && (failuresOnly(event.previousDocumentData, event.documentData) || recordsSentForm(event.previousDocumentData, event.documentData))))) {
           insertedDuringRun = true;
           flush().catch(() => {
           });
@@ -4397,13 +4436,14 @@ function createRegisterOutbox(options) {
     return {
       commandIds: stuck.map(([id2]) => id2),
       since: Math.min(...stuck.map(([, clock]) => clock.since)),
+      firstFailedAt: Math.min(...stuck.map(([, clock]) => clock.firstFailedAt)),
       reason: stuck.reduce((latest, entry) => entry[1].seq > latest[1].seq ? entry : latest)[1].reason,
-      orders: stuck.map(([commandId, { since, reason }]) => ({ commandId, since, reason }))
+      orders: stuck.map(([commandId, { since, firstFailedAt, reason }]) => ({ commandId, since, firstFailedAt, reason }))
     };
   }
   function serverFailed(commands, reason) {
     const at2 = now();
-    for (const { commandId } of commands) clocks.set(commandId, { since: clocks.get(commandId)?.since ?? at2, seq: ++failureSeq, reason });
+    for (const { commandId } of commands) clocks.set(commandId, { ...clocks.get(commandId) ?? { since: at2, firstFailedAt: at2 }, seq: ++failureSeq, reason });
   }
   async function updateState(patch = {}) {
     const pending = await countFresh(collection, { syncStatus: "pending" });
@@ -4601,28 +4641,70 @@ function createRegisterOutbox(options) {
   };
 }
 
-// src/outbox/use-order-outbox.ts
-import { useEffect as useEffect4, useMemo as useMemo4, useRef as useRef4, useState as useState4 } from "react";
+// src/outbox/use-register-outbox.ts
+import { useEffect as useEffect4, useRef as useRef4, useState as useState4 } from "react";
 var idle = { pending: 0, sending: false };
-var noneStuck = [];
-function useOrderOutbox(options) {
-  const { storeKey, deviceId } = options;
+function useRegisterOutbox(options) {
+  const { commands, deviceId } = options;
   const latest = useRef4(options);
   latest.current = options;
   const current = useRef4(null);
-  const openingError = useRef4(null);
-  const loggedMismatches = useRef4(/* @__PURE__ */ new Set());
-  const [orders, setOrders] = useState4(null);
   const [state, setState] = useState4(idle);
-  const [recent, setRecent] = useState4([]);
-  const savesInFlight = useRef4(0);
-  const [savesInFlightCount, setSavesInFlightCount] = useState4(0);
   useEffect4(() => {
+    setState(idle);
+    if (!commands) return;
+    const outbox = createRegisterOutbox({
+      collection: commands,
+      deviceId,
+      transport: latest.current.transport(),
+      isEnabled: latest.current.isEnabled ? () => latest.current.isEnabled?.() ?? true : void 0,
+      onResult: latest.current.onResult ? async (command, result) => {
+        await latest.current.onResult?.(command, result);
+      } : void 0,
+      backendNotFound: latest.current.backendNotFound
+    });
+    current.current = { commands, deviceId, outbox };
+    const status = outbox.state$.subscribe(setState);
+    outbox.start();
+    return () => {
+      outbox.stop();
+      status.unsubscribe();
+      current.current = null;
+      setState(idle);
+    };
+  }, [commands, deviceId]);
+  const opened = current.current;
+  return {
+    state: opened?.commands === commands && opened.deviceId === deviceId ? state : idle,
+    async flush() {
+      const active = current.current;
+      if (active?.commands === commands && active.deviceId === deviceId) await active.outbox.flush();
+    }
+  };
+}
+
+// src/outbox/use-order-outbox.ts
+import { useEffect as useEffect5, useMemo as useMemo4, useRef as useRef5, useState as useState5 } from "react";
+var idle2 = { pending: 0, sending: false };
+var noneStuck = [];
+function useOrderOutbox(options) {
+  const { storeKey, deviceId } = options;
+  const latest = useRef5(options);
+  latest.current = 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 savesInFlight = useRef5(0);
+  const [savesInFlightCount, setSavesInFlightCount] = useState5(0);
+  useEffect5(() => {
     let active = true;
     let dispose;
     openingError.current = null;
     setOrders(null);
-    setState(idle);
+    setState(idle2);
     setRecent([]);
     if (!storeKey) return;
     void latest.current.open(storeKey).then(async (store) => {
@@ -4660,7 +4742,7 @@ function useOrderOutbox(options) {
       dispose?.();
     };
   }, [storeKey, deviceId]);
-  useEffect4(() => {
+  useEffect5(() => {
     latest.current.onBusy?.(state.sending);
     return () => latest.current.onBusy?.(false);
   }, [state.sending]);
@@ -4669,7 +4751,7 @@ function useOrderOutbox(options) {
   const stuckCommandIds = useMemo4(() => stuckKey ? stuckKey.split(",") : noneStuck, [stuckKey]);
   return {
     orders: ready ? orders : null,
-    state: ready ? state : idle,
+    state: ready ? state : idle2,
     recent: ready ? recent : [],
     async flush() {
       const opened = current.current;
@@ -5040,6 +5122,7 @@ export {
   useCurrencyCode,
   useCurrencyFormatter,
   useOrderOutbox,
+  useRegisterOutbox,
   useRegisterSession,
   useSale,
   useStoreSettings,

package/package.json

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

package/src/index.ts

@@ -58,8 +58,8 @@ export type { SaleStage, CatalogueEntry } from './sale';
 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 { createRegisterOutbox, useRegisterOutbox } from './outbox';
+export type { RegisterOutboxOptions, RegisterOutbox, UseRegisterOutboxOptions, UseRegisterOutboxResult } from './outbox';
 export { createBackendNotFound } from './outbox/backend-not-found';
 export type { BackendNotFound } from './outbox/backend-not-found';
 export type { HttpTransportOptions, OrderOutboxOptions, OrderOutbox, TransportOutcome, CommandTransport, OutboxState, UseOrderOutboxOptions, UseOrderOutboxResult } from './outbox';

package/src/outbox/index.ts

@@ -4,6 +4,8 @@ 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 { useRegisterOutbox } from './use-register-outbox';
+export type { UseRegisterOutboxOptions, UseRegisterOutboxResult } from './use-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/order-outbox.ts

@@ -104,8 +104,9 @@ export function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox {
   // clock (`pausedAt`), and the next response the store answers, of any kind and for any order, resumes them all,
   // moving `since` on by the offline gap: a pause is about the connection. So `since` is when the clock would have
   // started had there been no offline gaps: now minus its answered time (while paused, as of the pause). Progress,
-  // or the order leaving pending, clears it.
-  const clocks = new Map<string, { since: number; pausedAt?: number; seq: number; reason: string }>();
+  // or the order leaving pending, clears it. `firstFailedAt` is the wall-clock time of the clock's first answered
+  // failure; a pause never moves it, and a clock restored from stored `serverFailures` has none (it is memory only).
+  const clocks = new Map<string, { since: number; firstFailedAt?: number; pausedAt?: number; seq: number; reason: string }>();
   let failureSeq = 0; // numbers failures, so `stuck` can name the latest reason
   // Timer runs alternate between the batch turn (the batch, or the walk's probe) and the isolated turn (one due
   // isolated order); a turn with nothing to send gives way to the other, so neither side can starve the other.
@@ -119,8 +120,11 @@ export function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox {
     const stuck = [...clocks].filter(([, clock]) => (clock.pausedAt ?? now()) - clock.since >= stuckAfter);
     if (!stuck.length) return undefined;
     return { commandIds: stuck.map(([id]) => id), since: Math.min(...stuck.map(([, clock]) => clock.since)),
+      ...(stuck.every(([, clock]) => clock.firstFailedAt !== undefined)
+        ? { firstFailedAt: Math.min(...stuck.map(([, clock]) => clock.firstFailedAt!)) } : {}),
       reason: stuck.reduce((latest, entry) => (entry[1].seq > latest[1].seq ? entry : latest))[1].reason,
-      orders: stuck.map(([commandId, { since, reason }]) => ({ commandId, since, reason })) };
+      orders: stuck.map(([commandId, { since, firstFailedAt, reason }]) => ({ commandId, since, reason,
+        ...(firstFailedAt === undefined ? {} : { firstFailedAt }) })) };
   }
 
   // An isolated order is due once its backoff has passed, or when the clock was set back further than any backoff.
@@ -166,6 +170,10 @@ export function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox {
   const bare = ({ serverFailures, _rev, _meta, ...data }: RxDocumentData<PosOrder>) => data;
   const failuresOnly = (before: RxDocumentData<PosOrder>, after: RxDocumentData<PosOrder>) =>
     !deepEqual(before.serverFailures, after.serverFailures) && deepEqual(bare(before), bare(after));
+  // The outbox's own write of an order's sent form (#300): the form frozen, and sentVersion stored on a first send.
+  // Not new work (medusapos/app#160). A changed sentVersion (a downgrade) is not this write.
+  const recordsSentForm = (before: RxDocumentData<PosOrder>, after: RxDocumentData<PosOrder>) =>
+    deepEqual(bare({ ...freezeSentForm(before), sentVersion: before.sentVersion ?? after.sentVersion } as RxDocumentData<PosOrder>), bare(after));
 
   // Every read bypasses the query cache. RxDB 17 fixed RxDB 16.21.1's bug 4 (rxdb#7067);
   // readFresh, countFresh and watchFresh remain correct public API.
@@ -186,7 +194,7 @@ export function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox {
   // floor for the retry: the store's Retry-After, or an isolated order's own backoff.
   function serverFailed(orders: PosOrder[], alone: 'probe' | 'isolated' | undefined, reason: string, retryAfterMs?: number) {
     const at = now();
-    for (const { commandId } of orders) clocks.set(commandId, { since: clocks.get(commandId)?.since ?? at, seq: ++failureSeq, reason });
+    for (const { commandId } of orders) clocks.set(commandId, { ...(clocks.get(commandId) ?? { since: at, firstFailedAt: at }), seq: ++failureSeq, reason });
     const id = orders[0].commandId;
     if (alone === 'isolated') {
       isolate(id, reason, retryAfterMs);
@@ -482,7 +490,8 @@ export function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox {
       if (!subscription) subscription = collection.$.subscribe((event) => {
         // An UPDATE without previousDocumentData counts as a change: a needless send costs a request, a skipped one a sale.
         if (event.documentData?.syncStatus === 'pending' && (event.operation === 'INSERT' || event.operation === 'UPDATE' &&
-          !(event.previousDocumentData !== undefined && failuresOnly(event.previousDocumentData, event.documentData)))) {
+          !(event.previousDocumentData !== undefined && (failuresOnly(event.previousDocumentData, event.documentData)
+            || recordsSentForm(event.previousDocumentData, event.documentData))))) {
           insertedDuringRun = true;
           flush().catch(() => {});
         }

package/src/outbox/register-outbox.ts

@@ -73,19 +73,20 @@ export function createRegisterOutbox(options: RegisterOutboxOptions): RegisterOu
   // of a register's ledger holds up the commands behind it, by design, since register facts apply in `seq` order.
   // In memory only: a restart starts with no clocks, and the first answered failure after it starts them afresh
   // (accepted: register commands are few, and a restart re-sends at once).
-  const clocks = new Map<string, { since: number; pausedAt?: number; seq: number; reason: string }>();
+  const clocks = new Map<string, { since: number; firstFailedAt: number; pausedAt?: number; seq: number; reason: string }>();
   let failureSeq = 0; // numbers failures, so `stuck` can name the latest reason
 
   function stuckState(): OutboxState['stuck'] {
     const stuck = [...clocks].filter(([, clock]) => (clock.pausedAt ?? now()) - clock.since >= stuckAfter);
     if (!stuck.length) return undefined;
     return { commandIds: stuck.map(([id]) => id), since: Math.min(...stuck.map(([, clock]) => clock.since)),
+      firstFailedAt: Math.min(...stuck.map(([, clock]) => clock.firstFailedAt)),
       reason: stuck.reduce((latest, entry) => (entry[1].seq > latest[1].seq ? entry : latest))[1].reason,
-      orders: stuck.map(([commandId, { since, reason }]) => ({ commandId, since, reason })) };
+      orders: stuck.map(([commandId, { since, firstFailedAt, reason }]) => ({ commandId, since, firstFailedAt, reason })) };
   }
   function serverFailed(commands: RegisterCommand[], reason: string) {
     const at = now();
-    for (const { commandId } of commands) clocks.set(commandId, { since: clocks.get(commandId)?.since ?? at, seq: ++failureSeq, reason });
+    for (const { commandId } of commands) clocks.set(commandId, { ...(clocks.get(commandId) ?? { since: at, firstFailedAt: at }), seq: ++failureSeq, reason });
   }
 
   async function updateState(patch: Partial<OutboxState> = {}) {

package/src/outbox/types.ts

@@ -27,8 +27,11 @@ export interface OutboxState {
   /** Set while the store (not offline) has kept failing some orders for 15 minutes, each on its own clock. Those
    * orders stay pending and keep retrying. `orders` has each order's own entry: its `since` is when its clock
    * would have started had there been no offline gaps (now minus its answered time; while offline, as of the
-   * moment the clock paused), and its latest `reason`. `since` is the earliest of theirs; `reason` the latest. */
-  stuck?: { commandIds: string[]; since: number; reason: string; orders: { commandId: string; since: number; reason: string }[] };
+   * moment the clock paused), and its latest `reason`. `since` is the earliest of theirs, virtual for the threshold;
+   * `reason` the latest. `firstFailedAt` is the earliest real wall-clock first failure, only when every stuck clock
+   * has one. Each order entry has its own real wall-clock `firstFailedAt`. Both are in memory only, absent after restart. */
+  stuck?: { commandIds: string[]; since: number; firstFailedAt?: number; reason: string;
+    orders: { commandId: string; since: number; firstFailedAt?: number; reason: string }[] };
   /** Set after 3 consecutive 404 answers (counted across the outboxes sharing one BackendNotFound): the store address
    * may be wrong, or the store's plugin isn't installed or is switched off. The outbox keeps retrying; the next answer
    * that isn't a 404 clears it (offline changes nothing). `since` is when the first of those 404s arrived. */

package/src/outbox/use-register-outbox.ts

@@ -0,0 +1,55 @@
+import type { RegisterCommandEnvelope } from '@tallyui/core';
+import { useEffect, useRef, useState } from 'react';
+import type { RegisterCommandCollection } from '../register/register-commands';
+import { createRegisterOutbox, type RegisterOutboxOptions } from './register-outbox';
+import type { CommandTransport, OutboxState } from './types';
+
+const idle: OutboxState = { pending: 0, sending: false };
+
+export interface UseRegisterOutboxOptions {
+  /** `register_commands` (see `registerCommandCollection()`); `null` while it opens or when there's no store. A new collection (a store switch) restarts the outbox. */
+  commands: RegisterCommandCollection | null;
+  /** Builds the transport; called when the outbox is created: on each new collection or device id (twice under React StrictMode's double effect, which stops the first outbox). */
+  transport(): CommandTransport<RegisterCommandEnvelope>;
+  /** The device id sent on every command. A change restarts the outbox. */
+  deviceId: string;
+  /** Passed through to createRegisterOutbox (same meaning). The latest function is called each time, so a new one does not restart the outbox. */
+  isEnabled?: () => boolean;
+  /** Called with each result. The latest function is called each time; a new one does not restart the outbox. */
+  onResult?: RegisterOutboxOptions['onResult'];
+  backendNotFound?: RegisterOutboxOptions['backendNotFound'];
+}
+export interface UseRegisterOutboxResult {
+  /** The outbox state, or idle ({ pending: 0, sending: false }) while there is no collection. */
+  state: OutboxState;
+  /** Sends pending till updates; does nothing while there is no collection. */
+  flush(): Promise<void>;
+}
+
+export function useRegisterOutbox(options: UseRegisterOutboxOptions): UseRegisterOutboxResult {
+  const { commands, deviceId } = options;
+  const latest = useRef(options);
+  latest.current = options;
+  const current = useRef<{ commands: RegisterCommandCollection; deviceId: string; outbox: ReturnType<typeof createRegisterOutbox> } | null>(null);
+  const [state, setState] = useState<OutboxState>(idle);
+
+  useEffect(() => {
+    setState(idle);
+    if (!commands) return;
+    const outbox = createRegisterOutbox({ collection: commands, deviceId, transport: latest.current.transport(),
+      isEnabled: latest.current.isEnabled ? () => latest.current.isEnabled?.() ?? true : undefined,
+      onResult: latest.current.onResult ? async (command, result) => { await latest.current.onResult?.(command, result); } : undefined,
+      backendNotFound: latest.current.backendNotFound });
+    current.current = { commands, deviceId, outbox };
+    const status = outbox.state$.subscribe(setState);
+    outbox.start();
+    return () => { outbox.stop(); status.unsubscribe(); current.current = null; setState(idle); };
+  }, [commands, deviceId]);
+
+  const opened = current.current;
+  return { state: opened?.commands === commands && opened.deviceId === deviceId ? state : idle,
+    async flush() {
+      const active = current.current;
+      if (active?.commands === commands && active.deviceId === deviceId) await active.outbox.flush();
+    } };
+}

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

@@ -8,11 +8,11 @@ export function withPricingContext(context: SyncContext, settings: StoreSettings
 }
 
 /**
- * `<TaxProvider>`'s props from the same settings, so its tax inclusivity and rounding match the store's. `custom`
+ * `<TaxProvider>`'s props from the same settings, so its tax inclusivity, rounding and rate codes match the store's. `custom`
  * rounding passes none, the default (#287). An explicit `rounding` prop after the spread still wins, since JSX
  * applies props in order; so `<TaxProvider {...taxProviderProps(s)} rounding={undefined}>` wipes the store's rounding.
  */
 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 }) };
+  return { ratesPpm: settings.taxRatesPpm, pricesIncludeTax: settings.pricesIncludeTax, ...(rounding && { rounding }), ...(settings.taxRateCodes && { rateCodes: settings.taxRateCodes }) };
 }

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

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
+import { errorKind, SignInError } from '@tallyui/core';
 import type { StoreSettings, StoreSettingsChoice, StoreSettingsChoices, TaxRounding } from '@tallyui/core';
 import { resolveStoreSettings } from './resolve-store-settings';
 import type { ResolveStoreSettingsOptions } from './resolve-store-settings';
@@ -7,19 +8,39 @@ export type StoreSettingsState =
   | { state: 'loading' }
   | { state: 'ready'; settings: StoreSettings; choice?: StoreSettingsChoice }
   | { state: 'choose'; choices: StoreSettingsChoices; initial?: StoreSettingsChoice; choose: (choice: StoreSettingsChoice) => void }
-  | { state: 'error'; error: unknown; retry: () => void }
+  | { state: 'error'; error: unknown; retry: () => void; nextRetryAt?: number }
   | { state: 'unsupported' };
 
 // One object, so re-entering loading while already loading doesn't re-render.
 const LOADING: StoreSettingsState = { state: 'loading' };
 
-// The store's taxRounding (#324): the context's capabilities, else one read of the connector's. A failure or no
-// value leaves the field out, the default rounding; so does a connector without `capabilities`, with no read.
+export class StoreCapabilitiesUnavailableError extends Error {
+  constructor(cause?: unknown) {
+    super('Store capabilities unavailable', { cause });
+    this.name = 'StoreCapabilitiesUnavailableError';
+  }
+}
+
+// Exponential retry for unknown rounding: 5 seconds, doubling up to 5 minutes.
+const INITIAL_RETRY_MS = 5_000;
+const MAX_RETRY_MS = 5 * 60_000;
+
+// The store's taxRounding (#324): the context's capabilities, else one read of the connector's.
 function readTaxRounding({ connector, context }: ResolveStoreSettingsOptions): Promise<TaxRounding | undefined> {
   if (context.capabilities) return Promise.resolve(context.capabilities.taxRounding);
   if (!connector.storeSettings || !connector.capabilities) return Promise.resolve(undefined);
   const read = connector.capabilities;
-  return Promise.resolve().then(() => read(context)).then((capabilities) => capabilities?.taxRounding, () => undefined);
+  return Promise.resolve().then(() => read(context)).then(
+    (capabilities) => {
+      if (!capabilities) throw new StoreCapabilitiesUnavailableError();
+      return capabilities.taxRounding;
+    },
+    (cause) => {
+      // The till must fix its own credentials or software; retrying cannot help.
+      if (errorKind(cause) === 'till' || (cause instanceof SignInError && cause.code === 'invalid_credentials')) throw cause;
+      throw new StoreCapabilitiesUnavailableError(cause);
+    },
+  );
 }
 
 /**
@@ -29,6 +50,10 @@ function readTaxRounding({ connector, context }: ResolveStoreSettingsOptions): P
  * The ready settings carry the store's `taxRounding` from the capabilities, so `taxProviderProps` passes it on (#324).
  * The capabilities are read beside the settings, before `ready`, so each resolve emits the settings once, with the
  * rounding already known: no later change of `settings` holds a sale.
+ * Unknown rounding keeps settings unresolved and retries by itself; show "Can't reach the store's settings yet. Retrying…" while `nextRetryAt` is set.
+ * A till-class or invalid-credentials sign-in error is not retried by itself, so the app prompts to sign in or update the till.
+ * An app shows a sign-in prompt when the `error` state's error is a `ConnectorUnauthorizedError` with `code: 'unauthorized'`
+ * or a `SignInError` with `code: 'invalid_credentials'`, and an update prompt for `code: 'till_update_required'`.
  *
  * ```tsx
  * const store = useStoreSettings({ connector, context, loadChoice, saveChoice });
@@ -44,6 +69,8 @@ export function useStoreSettings(options: ResolveStoreSettingsOptions): StoreSet
   const optionsRef = useRef(options);
   optionsRef.current = options;
   const requestRef = useRef(0);
+  const retryTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const retryDelayRef = useRef(INITIAL_RETRY_MS);
   const [state, setState] = useState<StoreSettingsState>(LOADING);
 
   // `from`, when given, is the request that created the `choose`/`retry` calling this: a call
@@ -52,6 +79,7 @@ export function useStoreSettings(options: ResolveStoreSettingsOptions): StoreSet
   // a pick doesn't read it again.
   const resolve = useCallback((choice?: StoreSettingsChoice, from?: number, known?: Promise<TaxRounding | undefined>) => {
     if (from !== undefined && from !== requestRef.current) return;
+    clearTimeout(retryTimerRef.current);
     const request = ++requestRef.current;
     const current = () => request === requestRef.current;
     setState(LOADING);
@@ -59,6 +87,7 @@ export function useStoreSettings(options: ResolveStoreSettingsOptions): StoreSet
     Promise.all([resolveStoreSettings(optionsRef.current, choice), rounding]).then(
       ([result, taxRounding]) => {
         if (!current()) return;
+        retryDelayRef.current = INITIAL_RETRY_MS;
         if (result.status === 'ready')
           setState({ state: 'ready', settings: taxRounding ? { ...result.settings, taxRounding } : result.settings, choice: result.choice });
         else if (result.status === 'choose')
@@ -67,7 +96,15 @@ export function useStoreSettings(options: ResolveStoreSettingsOptions): StoreSet
       },
       // A retry keeps the choice that failed: a new pick is saved only once it resolves.
       (error: unknown) => {
-        if (current()) setState({ state: 'error', error, retry: () => resolve(choice, request) });
+        if (!current()) return;
+        const retry = () => resolve(choice, request);
+        if (error instanceof StoreCapabilitiesUnavailableError) {
+          const delay = retryDelayRef.current;
+          const nextRetryAt = Date.now() + delay;
+          retryDelayRef.current = Math.min(delay * 2, MAX_RETRY_MS);
+          retryTimerRef.current = setTimeout(retry, delay);
+          setState({ state: 'error', error, retry, nextRetryAt });
+        } else setState({ state: 'error', error, retry });
       },
     );
   }, []);
@@ -76,6 +113,8 @@ export function useStoreSettings(options: ResolveStoreSettingsOptions): StoreSet
     resolve();
     // Discards the in-flight result on a store switch or unmount.
     return () => {
+      clearTimeout(retryTimerRef.current);
+      retryDelayRef.current = INITIAL_RETRY_MS;
       requestRef.current += 1;
     };
   }, [connector, context, resolve]);