@tallyui/pos 3.7.1 → 3.9.0

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

@@ -9,7 +9,7 @@
  *
  * Not ported (registers job c2 owns the server side; TallyUI has no refund model yet):
  * - `retryMovement` and `refusedMovements`: there's no outbox to refuse a movement (c2).
- * - Refund records, refund parents and their demand and close-time wait: no refund model.
+ * - Refund parents and the close-time wait: a refund's record is the app's optional `refunds` collection, and one still pending at close is listed on the Z instead (ADR-080 amendment 1).
  * - Anchor invalidation, `server_expected` and `server_sales_count`: no server figures (c2).
  * - `unsyncedCount` and the `sync_status` filters: nothing is sent (c2).
  * - The binding (`useRegisterBinding`) and `blind` from WooCommerce capabilities: app inputs.
@@ -17,13 +17,15 @@
 import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
 import { combineLatest, map, of, switchMap } from 'rxjs';
 import type { RxCollection } from 'rxdb';
-import type { ServerCapabilities } from '@tallyui/core';
+import type { RegisterSessionAlreadyOpenData, ServerCapabilities } from '@tallyui/core';
 import type { PosOrder } from '../pos-order/types';
+import type { PosRefund, PosRefundCollection } from '../refund/pos-refund';
 import { readFresh, watchFresh } from '../rxdb';
 import { deriveExpected, type LedgerRow } from './expected';
 import { recordRegisterFact, registerFactsLogger, type Actor } from './facts';
 import { closeNeedsApproval } from './register-count.helpers';
-import { reconcileRegisterCommands, registerCommandsLogger, type RegisterCommandCollection } from './register-commands';
+import { abandonSession, adoptRegisterResults, takeOverSession } from './register-adoption';
+import { reconcileRegisterCommands, registerCommandsLogger, type RegisterCommand, type RegisterCommandCollection } from './register-commands';
 import { observeRegister$, readRegister, type RegisterBucket, type RegisterDocument, type RegisterHost } from './register-document';
 import type { CashMovement, Closure, RegisterSession } from './schemas';
 import * as store from './session-store';
@@ -79,11 +81,15 @@ export interface UseRegisterSessionOptions {
   sessions: RegisterSessionCollection | null;
   /** `cash_movements`; `null` while it opens. */
   movements: CashMovementCollection | null;
+  /** `pos_refunds` (`posRefundCollection()`); `null` while it opens. Leave it out when the app takes no refunds (ADR-080 amendment 1). */
+  refunds?: PosRefundCollection | null;
   /** `closures`; `null` while it opens. */
   closures: ClosureCollection | null;
   /** `register_commands`, created with `registerCommandCollection()`; `null` while it opens. */
   commands?: RegisterCommandCollection | null;
   capabilities?: ServerCapabilities;
+  /** The till's name from the app's settings, sent on a register v2 open; the app supplies its platform fallback. */
+  deviceName?: string | null;
   /** `pos_orders`: a session's sales are those whose `sessionId` is its id. */
   orders: RxCollection<PosOrder> | null;
   /** The register document's host, for the closure number and perpetual totals (`writeClosure`); `null` while it opens. */
@@ -115,7 +121,8 @@ export interface UseRegisterSessionOptions {
 type Reservation = RegisterBucket['closure_reservation'];
 type Snapshot = {
   rows: RegisterSession[]; closureRows: Closure[]; reservation: Reservation;
-  entries: CashMovement[]; sales: PosOrder[];
+  entries: CashMovement[]; sales: PosOrder[]; refundRows: PosRefund[];
+  open?: RegisterCommand;
 };
 
 const reservationOf = (register: RegisterDocument | null, storeKey: string, registerId: string) =>
@@ -128,12 +135,13 @@ const unwritten = (row: RegisterSession, closureRows: readonly { id: string }[])
 /**
  * The session for this register: first the one an unapplied closure reservation names (its close
  * was interrupted after the number was reserved, perhaps after its row was written), so it can
- * finish; then the open or counting one; then a closed one whose closure row was never written; null if any status is unknown.
+ * finish; then the open or counting one; then a conflict one; then a closed one whose closure row was never written; null if any status is unknown.
  */
 function currentSession(rows: RegisterSession[], closureRows: Closure[], reservation: Reservation) {
   if (rows.some((row) => !store.isKnownSessionStatus(row.status))) return null;
   return (reservation && !reservation.applied ? rows.find((row) => row.id === reservation.row.session_id) : undefined)
-    ?? rows.find((row) => row.status !== 'closed')
+    ?? rows.find((row) => row.status === 'open' || row.status === 'counting')
+    ?? rows.find((row) => row.status === 'conflict')
     ?? rows.find((row) => unwritten(row, closureRows))
     ?? null;
 }
@@ -148,11 +156,11 @@ function ledgerRows(orders: readonly PosOrder[]): LedgerRow[] {
 
 export function useRegisterSession(options: UseRegisterSessionOptions) {
   const { sessions, movements, closures, orders, register, storeKey, registerId, enabled, actor, timezone, tenderInProgress, expectedCloseTime, labels } = options;
-  const { commands } = options;
+  const { commands, refunds } = options;
   const commandEnabled = (options.capabilities?.register ?? 0) >= 1;
   const commandTarget = useMemo(() => enabled && commandEnabled && commands && sessions && movements && closures && register && registerId
-    ? { commands, sessions, movements, closures, host: register, storeKey, registerId } : null,
-  [enabled, commandEnabled, commands, sessions, movements, closures, register, storeKey, registerId]);
+    ? { commands, sessions, movements, closures, host: register, storeKey, registerId, registerContract: options.capabilities?.register, deviceName: options.deviceName } : null,
+  [enabled, commandEnabled, commands, sessions, movements, closures, register, storeKey, registerId, options.capabilities?.register, options.deviceName]);
   const commandTargetRef = useRef(commandTarget);
   commandTargetRef.current = commandTarget;
   const reconcile = (row?: RegisterSession) => {
@@ -167,21 +175,30 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
     });
   };
   useEffect(reconcile, [commandTarget]);
+  useEffect(() => {
+    if (!commandTarget) return;
+    const subscription = commandTarget.commands.find({ selector: { registerId: commandTarget.registerId } }).$.subscribe(() => {
+      void adoptRegisterResults(commandTarget);
+    });
+    return () => subscription.unsubscribe();
+  }, [commandTarget]);
   const source = useMemo(() => {
-    if (!enabled || !sessions || !movements || !closures || !orders || !registerId || !register) return null;
+    if (!enabled || !sessions || !movements || !closures || !orders || !registerId || !register || refunds === null) return null;
     return combineLatest([
       watchFresh(sessions, { selector: { register_id: registerId } }),
       watchFresh(closures, { selector: { register_id: registerId } }),
       observeRegister$(register).pipe(map((document) => reservationOf(document, storeKey, registerId))),
     ]).pipe(switchMap(([rows, closureRows, reservation]) => {
       const current = currentSession(rows, closureRows, reservation);
-      if (!current) return of({ rows, closureRows, reservation, entries: [], sales: [] } as Snapshot);
+      if (!current) return of({ rows, closureRows, reservation, entries: [], sales: [], refundRows: [] } as Snapshot);
       return combineLatest([
         watchFresh(movements, { selector: { session_id: current.id } }),
         watchFresh(orders, { selector: { sessionId: current.id } }),
-      ]).pipe(map(([entries, sales]) => ({ rows, closureRows, reservation, entries, sales })));
+        commandTarget ? watchFresh(commandTarget.commands, { selector: { key: `session.open:${current.id}` } }) : of([]),
+        refunds ? watchFresh(refunds, { selector: { sessionId: current.id } }) : of([]),
+      ]).pipe(map(([entries, sales, opens, refundRows]) => ({ rows, closureRows, reservation, entries, sales, open: opens[0], refundRows })));
     }));
-  }, [enabled, sessions, movements, closures, orders, register, storeKey, registerId]);
+  }, [enabled, sessions, movements, closures, orders, register, storeKey, registerId, commandTarget, refunds]);
   // A latest-value ref: an `actions` object from an earlier render still sees the current flag.
   const tender = useRef(tenderInProgress);
   tender.current = tenderInProgress;
@@ -251,10 +268,16 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
     }
   }, [data, source]);
   const session = data ? currentSession(data.rows, data.closureRows, data.reservation) : null;
+  const refusal = data?.open?.error?.data as RegisterSessionAlreadyOpenData | undefined;
+  const conflict = session?.status !== 'conflict' || !commandTarget ? undefined
+    : data?.open?.syncStatus === 'pending' && typeof data.open.payload.supersedes === 'string'
+      ? { sessionId: data.open.payload.supersedes, takingOver: true }
+      : data?.open?.syncStatus === 'rejected' && refusal
+        ? { sessionId: refusal.sessionId, openedAt: refusal.openedAt, openedBy: refusal.openedBy, deviceName: refusal.deviceName, takingOver: false } : undefined;
   const entries = data?.entries ?? [];
   const sales = data?.sales ?? [];
   const expected = session
-    ? deriveExpected({ session: { id: session.id, countedFloatMinor: session.counted_float_minor }, movements: entries, ledgerRowsBySession: ledgerRows(sales) })
+    ? deriveExpected({ session: { id: session.id, countedFloatMinor: session.counted_float_minor }, movements: entries, ledgerRowsBySession: ledgerRows(sales), refunds: data?.refundRows ?? [] })
     : {};
   const now = new Date();
   const [hour, minute] = String(expectedCloseTime ?? '').split(':').map(Number);
@@ -268,8 +291,8 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
     return id === null ? null : { id, sessions: sessions as RegisterSessionCollection };
   };
   const live = () => {
-    if (!enabled || !sessions || !movements || !closures || !orders || !registerId || !register) throw new RegisterSessionRequiredError();
-    return { sessions, movements, closures, orders, registerId, register };
+    if (!enabled || !sessions || !movements || !closures || !orders || !registerId || !register || refunds === null) throw new RegisterSessionRequiredError();
+    return { sessions, movements, closures, orders, registerId, register, refunds };
   };
   const current = () => {
     if (!session) throw new RegisterSessionRequiredError();
@@ -282,6 +305,8 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
 
   return {
     session,
+    /** The other till's live session, or the session this till is waiting to take over. */
+    conflict,
     /** Any unknown session status in the current snapshot means the register needs upgrade. */
     needsUpgrade: data?.rows.some((row) => !store.isKnownSessionStatus(row.status)) ?? false,
     movements: entries,
@@ -297,17 +322,34 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
     enabled,
     blind: options.blind ?? false,
     /** Pass straight to useSale's `session` option: `complete()` then stamps through `stampSession`. */
-    saleSession: session && sessions && session.status !== 'closed' ? { id: session.id, sessions } : undefined,
+    saleSession: session && sessions && (session.status === 'open' || session.status === 'counting') ? { id: session.id, sessions } : undefined,
     /** The open session's id, `null` when sessions are off, else `RegisterSessionRequiredError`. Call it when tender starts and before a card terminal captures. */
     requireOpen,
     /** `requireOpen()`, returning `{ id, sessions }`: pass it to useSale's `startTender`, which pins it (the rendered `saleSession` can lag). */
     requireSaleSession,
     actions: {
+      takeOver: async () => {
+        if (!commandTarget) throw new RegisterSessionRequiredError();
+        const row = currentSession(await readFresh(commandTarget.sessions, { selector: { register_id: commandTarget.registerId } }),
+          await readFresh(commandTarget.closures, { selector: { register_id: commandTarget.registerId } }),
+          reservationOf(await readRegister(commandTarget.host), commandTarget.storeKey, commandTarget.registerId));
+        if (row?.status !== 'conflict') throw new RegisterSessionRequiredError();
+        await takeOverSession({ ...commandTarget, sessionId: row.id, registerContract: options.capabilities?.register });
+      },
+      chooseAnotherRegister: async () => {
+        if (!commandTarget) throw new RegisterSessionRequiredError();
+        const row = currentSession(await readFresh(commandTarget.sessions, { selector: { register_id: commandTarget.registerId } }),
+          await readFresh(commandTarget.closures, { selector: { register_id: commandTarget.registerId } }),
+          reservationOf(await readRegister(commandTarget.host), commandTarget.storeKey, commandTarget.registerId));
+        if (row?.status !== 'conflict') throw new RegisterSessionRequiredError();
+        await abandonSession({ ...commandTarget, sessionId: row.id });
+      },
       /**
        * Refuses with `RegisterSessionAlreadyOpenError` while the register has a live session or
        * another open is running (in any hook instance), and with `RegisterCloseIncompleteError`
        * while an earlier close hasn't finished: a new session would lock the till behind it.
        * An unknown stored status refuses with `RegisterNeedsUpgradeError`.
+       * A conflict session refuses with `RegisterSessionConflictError`; superseded and abandoned sessions do not block.
        */
       openSession: async (input: { expectedFloatMinor: number | null; countedFloatMinor: number }) => {
         // A double tap: the second call sees the first's promise, set before its first await.
@@ -318,7 +360,8 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
           // The storage, not the rendered snapshot or a cached query, which can lag a new write.
           const rows = await readFresh(sessions, { selector: { register_id: registerId } });
           if (rows.some((row) => !store.isKnownSessionStatus(row.status))) throw new store.RegisterNeedsUpgradeError();
-          if (rows.some((row) => row.status !== 'closed')) throw new RegisterSessionAlreadyOpenError();
+          if (rows.some((row) => row.status === 'conflict')) throw new store.RegisterSessionConflictError();
+          if (rows.some((row) => row.status === 'open' || row.status === 'counting')) throw new RegisterSessionAlreadyOpenError();
           // Closure rows before the reservation: a close reserves, then inserts its row, then applies the
           // reservation, so a close landing between the two reads is still caught by one of them.
           const closureRows = await readFresh(closures, { selector: { register_id: registerId } });
@@ -380,7 +423,7 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
         const key = registerId ?? '';
         if (closingByRegister.has(key)) return closingByRegister.get(key)!;
         const run = (async () => {
-        const { sessions, movements, closures, orders, register } = live();
+        const { sessions, movements, closures, orders, register, refunds } = live();
         const open = current();
         // The gate reads the stored session and the Z's own inputs past the query cache, not this
         // render's snapshot, which can lag a sale or a close that already landed (#168 review).
@@ -392,6 +435,7 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
             session: { id: stored.id, countedFloatMinor: stored.counted_float_minor },
             movements: await readFresh(movements, { selector: { session_id: stored.id } }),
             ledgerRowsBySession: ledgerRows(await readFresh(orders, { selector: { sessionId: stored.id } })),
+            refunds: refunds ? await readFresh(refunds, { selector: { sessionId: stored.id } }) : undefined,
           });
           if (closeNeedsApproval(input.counted.cash ?? 0, fresh.cash ?? 0, options.varianceThreshold)) throw new RegisterApprovalRequiredError();
         }
@@ -408,6 +452,7 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
           counted: cash, otherTenders, timezone, softwareVersion: options.softwareVersion,
           movements: await readFresh(movements, { selector: { session_id: closed.id } }),
           orders: await readFresh(orders, { selector: { sessionId: closed.id } }),
+          refunds: refunds ? await readFresh(refunds, { selector: { sessionId: closed.id } }) : undefined,
           resolveCashierName: labels?.resolveCashierName,
           labels: {
             register_name: labels?.registerName ?? '', closed_by_name: nameOf(closed.closed_by),