@tallyui/pos 3.8.0 → 3.9.0

package/src/register/session-store.ts

@@ -4,8 +4,8 @@
  *
  * Everything here writes local-only collections (`schemas.ts`). WCPOS's outbox (`pending`,
  * `retryMovement`) moves to registers job c. A session's sales are the `pos_orders` documents
- * whose `sessionId` is the session's id, and their payments are its ledger rows. Refunds are
- * not attributed yet (no refund model, as in `deriveExpected`). The frozen closure's money
+ * whose `sessionId` is the session's id, and their payments are its ledger rows.
+ * A session's refunds are its applied `pos_refunds` records, when the app passes them (ADR-080 amendment 1). The frozen closure's money
  * breakdowns (`payment_methods`, `opening_float`, `movements`, `tax_rates`) are minor-unit
  * integers, the same convention as the closure row itself; `closure-document.ts` converts them
  * to the decimal strings its envelope carries.
@@ -13,8 +13,9 @@
 import type { RxCollection } from 'rxdb';
 import { DEFAULT_TAX_ROUNDING, taxLinesByRate } from '../tax/exact';
 import type { PosOrder } from '../pos-order/types';
+import type { PosRefund } from '../refund/pos-refund';
 import { readFresh } from '../rxdb';
-import { deriveExpected, type LedgerRow } from './expected';
+import { deriveExpected, refundAmounts, type LedgerRow } from './expected';
 import { recordRegisterFact } from './facts';
 import { MAX_REASON_LENGTH } from './movement-input';
 import { countVariance } from './register-count.helpers';
@@ -440,6 +441,7 @@ export async function voidMovement(
  * Only a closed session (`closed` with `closed_at_gmt`) has a closure, and a closed session is
  * final, so its existing closure is returned as it was frozen. Orders the server rejected still
  * count in the drawer, because the cash was taken.
+ * A refund still pending at close is not counted, and the Z lists it.
  */
 export async function writeClosure({
   closures,
@@ -450,6 +452,7 @@ export async function writeClosure({
   otherTenders,
   movements,
   orders,
+  refunds,
   tillExpected,
   labels,
   resolveCashierName,
@@ -467,6 +470,8 @@ export async function writeClosure({
   movements: readonly CashMovement[];
   /** Any `pos_orders`; only those whose `sessionId` is this session's are counted. */
   orders: readonly PosOrder[];
+  /** `pos_refunds` rows; only this session's applied ones are counted (ADR-080 amendment 1). */
+  refunds?: readonly PosRefund[];
   tillExpected?: Record<string, number>;
   labels?: { register_name: string; closed_by_name: string; opened_by_name?: string; approved_by_name?: string };
   resolveCashierName?: (id: string) => string;
@@ -486,6 +491,7 @@ export async function writeClosure({
     return existing;
   }
   const bound = orders.filter((order) => order.sessionId === session.id);
+  const countedRefunds = (refunds ?? []).filter((refund) => refund.status === 'applied' && refund.sessionId === session.id);
   // Each payment is captured, and a cash payment's amount is already net of change.
   const rows: LedgerRow[] = bound.flatMap((order) =>
     order.payments.map((payment) => ({
@@ -503,6 +509,7 @@ export async function writeClosure({
       session: { id: session.id, countedFloatMinor: session.counted_float_minor },
       movements: entries,
       ledgerRowsBySession: rows,
+      refunds,
     });
   const counts = { cash: counted, ...otherTenders };
   const sum = (values: number[]) => values.reduce((total, value) => total + value, 0);
@@ -511,6 +518,11 @@ export async function writeClosure({
     const method = row.kind === 'cash' ? 'cash' : row.method_id;
     payment_methods[method] = { sales_minor: (payment_methods[method]?.sales_minor ?? 0) + row.amountMinor, refunds_minor: 0 };
   }
+  for (const refund of countedRefunds) {
+    for (const [method, amount] of refundAmounts(refund)) {
+      payment_methods[method] = { sales_minor: payment_methods[method]?.sales_minor ?? 0, refunds_minor: (payment_methods[method]?.refunds_minor ?? 0) + amount };
+    }
+  }
   // Same per-rate split a receipt shows (`taxLinesByRate`), run per order so each order's rates
   // add up to its own taxMinor, then summed across the session's orders by rate. A line's own
   // taxInclusive overrides the order's, matching PosOrderLine's own fallback convention. Each order is split by the
@@ -552,7 +564,7 @@ export async function writeClosure({
       Object.entries(counts).map(([method, value]) => [method, countVariance(value, till_expected[method] ?? 0)]),
     ),
     period_sales_total_minor: sum(rows.map((row) => row.amountMinor)),
-    period_refunds_total_minor: 0,
+    period_refunds_total_minor: sum(countedRefunds.flatMap((refund) => refundAmounts(refund).map(([, amount]) => amount))),
     perpetual_sales_total_minor: 0,
     perpetual_refunds_total_minor: 0,
     unsynced_count: unsynced.length,
@@ -581,7 +593,11 @@ export async function writeClosure({
         id, type, amountMinor, reason, voids: voids ?? null, created_at_gmt, created_by: created_by ?? null, voided_by: voided_by ?? null,
       })),
       transaction_count: bound.length,
-      refund_count: 0,
+      refund_count: countedRefunds.length,
+      ...(refunds !== undefined ? {
+        refund_ids: countedRefunds.map((refund) => refund.id),
+        pending_refund_ids: refunds.filter((refund) => refund.status === 'pending' && refund.sessionId === session.id).map((refund) => refund.id),
+      } : {}),
       cashiers: [...new Set(bound.map((order) => order.cashierRef ?? '').filter(Boolean))].map((id) => ({
         id,
         name: resolveCashierName?.(id) || id,

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.
@@ -19,6 +19,7 @@ import { combineLatest, map, of, switchMap } from 'rxjs';
 import type { RxCollection } from 'rxdb';
 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';
@@ -80,6 +81,8 @@ 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. */
@@ -118,7 +121,7 @@ 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;
 };
 
@@ -153,7 +156,7 @@ 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, registerContract: options.capabilities?.register, deviceName: options.deviceName } : null,
@@ -180,21 +183,22 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
     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 } }),
         commandTarget ? watchFresh(commandTarget.commands, { selector: { key: `session.open:${current.id}` } }) : of([]),
-      ]).pipe(map(([entries, sales, opens]) => ({ rows, closureRows, reservation, entries, sales, open: opens[0] })));
+        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, commandTarget]);
+  }, [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;
@@ -273,7 +277,7 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
   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);
@@ -287,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();
@@ -330,8 +334,7 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
           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();
-        if ((options.capabilities?.register ?? 0) < 2) throw new store.RegisterTakeOverError('REGISTER_TAKEOVER_UNSUPPORTED');
-        await takeOverSession({ ...commandTarget, sessionId: row.id });
+        await takeOverSession({ ...commandTarget, sessionId: row.id, registerContract: options.capabilities?.register });
       },
       chooseAnotherRegister: async () => {
         if (!commandTarget) throw new RegisterSessionRequiredError();
@@ -420,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).
@@ -432,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();
         }
@@ -448,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),