@tallyui/pos 3.0.0-next.1 → 3.0.0

package/dist/index.d.ts

@@ -210,6 +210,9 @@ type StoreSettingsState = {
  * 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 });
@@ -1950,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;
         }[];
     };
@@ -2043,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 {
@@ -2249,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

@@ -324,6 +324,7 @@ function taxProviderProps(settings) {
 
 // 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) {
@@ -343,6 +344,7 @@ function readTaxRounding({ connector, context }) {
       return capabilities.taxRounding;
     },
     (cause) => {
+      if (errorKind(cause) === "till" || cause instanceof SignInError && cause.code === "invalid_credentials") throw cause;
       throw new StoreCapabilitiesUnavailableError(cause);
     }
   );
@@ -3563,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;
@@ -3650,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()`). */
@@ -3970,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) {
@@ -4023,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);
@@ -4428,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" });
@@ -4632,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) => {
@@ -4691,7 +4742,7 @@ function useOrderOutbox(options) {
       dispose?.();
     };
   }, [storeKey, deviceId]);
-  useEffect4(() => {
+  useEffect5(() => {
     latest.current.onBusy?.(state.sending);
     return () => latest.current.onBusy?.(false);
   }, [state.sending]);
@@ -4700,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;
@@ -5071,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.1",
+  "version": "3.0.0",
   "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.1",
+    "@tallyui/core": "^3.0.0",
     "react": ">=18",
     "rxdb": "~17.5.0",
     "rxjs": ">=7"
   },
   "devDependencies": {
-    "@tallyui/core": "3.0.0-next.1",
+    "@tallyui/core": "3.0.0",
     "@types/react": ">=18",
     "react": "^19.2.4",
     "rxdb": "17.5.0",
     "rxjs": "7.8.2",
-    "@tallyui/connector-medusa": "3.0.0-next.1",
-    "@tallyui/connector-woocommerce": "3.0.0-next.1",
-    "@tallyui/database": "3.0.0-next.1"
+    "@tallyui/connector-medusa": "3.0.0",
+    "@tallyui/connector-woocommerce": "3.0.0",
+    "@tallyui/database": "3.0.0"
   },
   "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.
@@ -190,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);

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/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';
@@ -34,7 +35,11 @@ function readTaxRounding({ connector, context }: ResolveStoreSettingsOptions): P
       if (!capabilities) throw new StoreCapabilitiesUnavailableError();
       return capabilities.taxRounding;
     },
-    (cause) => { throw new StoreCapabilitiesUnavailableError(cause); },
+    (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);
+    },
   );
 }
 
@@ -46,6 +51,9 @@ function readTaxRounding({ connector, context }: ResolveStoreSettingsOptions): P
  * 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 });