@tallyui/pos 0.1.0 → 2.0.0

package/src/register/expected.ts

@@ -0,0 +1,66 @@
+/**
+ * What the register should hold at close, per tender method: the session's cash float plus
+ * captured payments and cash movements — never what the cashier counts. Port provenance
+ * (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`.
+ *
+ * **Refund attribution is deferred.** WCPOS's `attributeRefunds` debits a session's drawer for
+ * refunds processed against its captured payments (by stamped session, then by a legacy
+ * `refunded_amount` fallback). TallyUI has no refund model yet (ADR-032 amendment 1), so
+ * `deriveExpected` covers only the float, the session's captured payment rows, and its
+ * paid-in/paid-out cash movements under WCPOS's void rules.
+ */
+
+/** `session_id`, `kind`, `method_id`, `status` kept as WCPOS names them; money is TallyUI's integer-minor-units convention. */
+export type LedgerRow = {
+  session_id?: string | null;
+  kind: string;
+  method_id: string;
+  status: string;
+  amountMinor: number;
+};
+
+/** `type`, `voids` and `voided_by` are kept as WCPOS names them: neutral across backends. */
+export type Movement = {
+  id: string;
+  session_id: string;
+  type: string;
+  amountMinor: number;
+  voided_by?: string | null;
+  voids?: string | null;
+};
+
+/**
+ * Expected totals per tender method: the counted float, plus every captured ledger row for the
+ * session (grouped under `cash` for cash rows, else `method_id`), plus its non-voided
+ * paid-in/paid-out movements.
+ *
+ * A movement is excluded when its own `voided_by` is set, or when a `type: 'void'` row's
+ * `voids` names its id; the `void` row itself carries no amount of its own.
+ */
+export function deriveExpected({
+  session,
+  movements,
+  ledgerRowsBySession,
+}: {
+  session: { id: string; countedFloatMinor: number };
+  movements: readonly Movement[];
+  ledgerRowsBySession: readonly LedgerRow[];
+}): Record<string, number> {
+  const totals: Record<string, number> = { cash: session.countedFloatMinor };
+  for (const row of ledgerRowsBySession) {
+    if (row.session_id !== session.id || row.status !== 'captured') continue;
+    const method = row.kind === 'cash' ? 'cash' : row.method_id;
+    totals[method] = (totals[method] ?? 0) + row.amountMinor;
+  }
+  const voids = new Set(
+    movements
+      .filter((row) => row.session_id === session.id && row.type === 'void')
+      .map((row) => row.voids),
+  );
+  for (const row of movements) {
+    if (row.session_id !== session.id || row.voided_by || voids.has(row.id)) continue;
+    if (row.type === 'paid_in') totals.cash += row.amountMinor;
+    if (row.type === 'paid_out') totals.cash -= row.amountMinor;
+  }
+  return totals;
+}

package/src/register/export-csv.ts

@@ -0,0 +1,74 @@
+/**
+ * A CSV export of the closures currently shown: one column per tender the visible rows use, an
+ * expected-only tender kept as a zero-counted shortage, quoted/escaped cells with a CRLF line
+ * ending, and a leading `'` on formula- or control-prefixed text so a spreadsheet reads it as
+ * text (LEDGER.md #26, #27). Port provenance (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`
+ * `export-csv.ts`. Money is a2's integer minor units: an `exponent` parameter (as in a1's
+ * `parseMinor`/`varianceText`) formats each cell back to the decimal string WCPOS's server sent,
+ * e.g. `1250` at exponent 2 becomes `'12.50'`.
+ */
+import { minorToDecimal } from './money';
+import type { Closure } from './schemas';
+
+/** Widens a tender-map lookup back to `number | undefined`: a method absent from the map. */
+const at = (map: Record<string, number>, key: string): number | undefined => map[key];
+
+export function exportCsv(
+  rows: readonly Closure[],
+  exponent: number,
+  t: (key: string) => string,
+  names: Record<string, string> = {},
+  storeName = '',
+) {
+  const tenders = [
+    ...new Set(
+      rows.flatMap((row) => [
+        ...Object.keys(row.expected),
+        ...Object.keys(row.counted),
+        ...Object.keys(row.variance),
+      ]),
+    ),
+  ];
+  const cell = (value: unknown) => {
+    const text = String(value ?? '');
+    return `"${(/^(?:[\t\r\n]|[\s\x00-\x1f\x7f-\x9f]*[=+\-@])/.test(text) ? "'" + text : text).replace(/"/g, '""')}"`;
+  };
+  const header = ['business_day', 'closure', 'register', 'store', 'opened', 'closed', 'closer'].map((key) =>
+    t(`reports.csv_${key}`),
+  );
+  header.push(
+    ...tenders.flatMap((method) => [
+      `${t('reports.document.expected')} (${method})`,
+      `${t('register.counted')} (${method})`,
+      `${t('register.variance')} (${method})`,
+    ]),
+    t('reports.csv_status'),
+  );
+  return [
+    header,
+    ...rows.map((row) => [
+      row.business_day,
+      row.number,
+      row.breakdowns.register_name || names[row.register_id] || row.register_id.slice(0, 8),
+      row.breakdowns.store_name || storeName || row.store_key,
+      row.opened_at,
+      row.closed_at,
+      row.breakdowns.closed_by_name || t('register.unknown_cashier'),
+      ...tenders.flatMap((method) => {
+        const expected = at(row.expected, method);
+        const counted = at(row.counted, method) ?? (expected === undefined ? undefined : 0);
+        const value = at(row.variance, method) ?? (expected === undefined ? undefined : (counted ?? 0) - expected);
+        return [
+          expected === undefined ? '' : minorToDecimal(expected, exponent),
+          counted === undefined ? '' : minorToDecimal(counted, exponent),
+          value === undefined
+            ? ''
+            : `${minorToDecimal(Math.abs(value), exponent)} ${t(value < 0 ? 'register.short' : value > 0 ? 'register.over' : 'reports.exact')}`,
+        ];
+      }),
+      row.unsynced_count > 0 ? t('register.unsynced') : row.corrections_count ? t('reports.corrected') : '',
+    ]),
+  ]
+    .map((row) => row.map(cell).join(','))
+    .join('\r\n');
+}

package/src/register/facts.ts

@@ -0,0 +1,109 @@
+/**
+ * Register facts (ADR-032): a closed vocabulary of human register actions, logged through
+ * TallyUI's own logger. Port provenance (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`
+ * `audit.ts`, `RegisterFact` and `recordRegisterFact` only — `useRegisterActor` is React and
+ * belongs to job c, and so do the outbox/bridge-diagnostic facts (`outbox-approval-refused`,
+ * `outbox-request-failed`, `movement-retry-requested`, `movement-accepted`, `session-adopted`,
+ * `session-pruned`, `binding-changed`, `binding-removed`, `directory-unavailable`,
+ * `bridge-cycle-failed`): a2 has no outbox or hardware-bridge concept yet to attach them to.
+ *
+ * Neutral changes from the WCPOS source: WCPOS's `mintUuid` (`register-document.ts`) becomes
+ * a2's own; a person id (`approvedBy`) is a2's string id, not WCPOS's numeric one; money fields
+ * are a2's integer minor units, matching `CashMovement.amountMinor` and `Closure.counted`/
+ * `variance`.
+ *
+ * TallyUI's own addition (registers c1a): `late-sale`, a sale whose money was taken but whose
+ * session refused the stamp (ADR-032 amendment "Late sale"). Its `sessionId` is the session it
+ * tried, and its durable subject is the order.
+ */
+import { createLogger } from '../logging';
+import { mintUuid } from './register-document';
+import type { CashMovement, Closure, RegisterSession } from './schemas';
+
+/** The register-session logging scope; the app attaches its own sinks (console, remote, toast). */
+export const registerFactsLogger = createLogger('register-session');
+
+const attempt = () => ({ operationId: mintUuid().replace(/-/g, '') });
+
+export type Actor = { id: string; name: string };
+type Pair = { sessionId: string | undefined; registerId: string | null | undefined };
+type Human = Pair & { actor: Actor };
+type Movement = Pair & { movementId: string; movementType: CashMovement['type']; amount: number };
+
+type SimpleKind = 'counting-started' | 'counting-abandoned' | 'approval-refused' | 'x-report-dispatched' | 'drawer-dispatched';
+export type RegisterFact =
+  | (Human & { kind: 'session-opened'; amount: number; variance: RegisterSession['opening_variance_minor'] })
+  | (Human & { kind: SimpleKind })
+  | (Human & { kind: 'session-closed'; closureId: string } & Pick<Closure, 'number' | 'counted' | 'variance'>)
+  | (Human & Movement & { kind: 'movement-recorded' })
+  | (Human & Movement & { kind: 'movement-voided'; voids: string })
+  | (Human & { kind: 'approval-granted'; approvedBy: string | null })
+  | (Human & { kind: 'variance-over-threshold'; variance: number; threshold: number | undefined })
+  | (Pair & { kind: 'late-sale'; orderId: string; actor?: Actor });
+
+/** A human action without its own durable record gets a fresh attempt id; a durable action (a
+ * session, a movement or a late sale's order) uses the stable id of its subject. */
+function identity(fact: RegisterFact): { operationId: string } {
+  switch (fact.kind) {
+    case 'session-opened':
+      return { operationId: fact.sessionId?.replace(/-/g, '') ?? '' };
+    case 'session-closed':
+      return { operationId: fact.closureId.replace(/-/g, '') };
+    case 'movement-recorded':
+    case 'movement-voided':
+      return { operationId: fact.movementId.replace(/-/g, '') };
+    case 'late-sale':
+      return { operationId: fact.orderId.replace(/-/g, '') };
+    default:
+      return attempt();
+  }
+}
+
+export function recordRegisterFact(fact: RegisterFact): void {
+  const terminal = identity(fact);
+  const pair = { sessionId: fact.sessionId, registerId: fact.registerId };
+  const emit = (
+    message: string,
+    type: string,
+    context: Record<string, unknown> = {},
+    level: 'info' | 'warn' = 'info',
+  ) => registerFactsLogger[level](message, { actor: fact.actor, terminal, context: { type, ...pair, ...context } });
+  switch (fact.kind) {
+    case 'session-opened':
+      return emit('Register session opened', 'register.session-opened', { amount: fact.amount, variance: fact.variance });
+    case 'counting-started':
+      return emit('Register session counting started', 'register.counting-started');
+    case 'counting-abandoned':
+      return emit('Register session counting abandoned', 'register.counting-abandoned');
+    case 'session-closed':
+      return emit('Register session closed', 'register.session-closed', {
+        closureId: fact.closureId, number: fact.number, counted: fact.counted, variance: fact.variance,
+      });
+    case 'movement-recorded':
+      // No-sale is the cashier action, independent of drawer dispatch, and makes no cash claim.
+      if (fact.movementType === 'no_sale')
+        return emit('Register no-sale recorded', 'register.no-sale-recorded', { movementId: fact.movementId });
+      return emit('Register cash movement recorded', 'register.movement-recorded', {
+        movementId: fact.movementId, movementType: fact.movementType, amount: fact.amount,
+      });
+    case 'movement-voided':
+      return emit('Register cash movement voided', 'register.movement-voided', {
+        movementId: fact.movementId, movementType: fact.movementType, amount: fact.amount, voids: fact.voids,
+      });
+    case 'approval-granted':
+      return emit('Register session approval granted', 'register.approval-granted', { approvedBy: fact.approvedBy });
+    case 'approval-refused':
+      return emit('Register session approval refused', 'register.approval-refused', {}, 'warn');
+    case 'variance-over-threshold':
+      return emit('Register count exceeds variance threshold', 'register.variance-over-threshold',
+        { variance: fact.variance, threshold: fact.threshold }, 'warn');
+    // These prove dispatch success, not that paper printed or a physical drawer opened.
+    case 'x-report-dispatched':
+      return emit('Register X-report print dispatched', 'register.x-report-printed');
+    case 'drawer-dispatched':
+      return emit('Register drawer kick dispatched', 'register.drawer-opened');
+    // The money was taken, so the sale is kept and queued, outside every closure.
+    case 'late-sale':
+      return emit('Register late sale kept outside its session', 'register.late-sale', { orderId: fact.orderId }, 'warn');
+  }
+}

package/src/register/index.ts

@@ -0,0 +1,30 @@
+export { normalizeAmount, isServerDecimal, movementFieldError } from './movement-input';
+export type { MovementType } from './movement-input';
+export { deriveExpected } from './expected';
+export type { LedgerRow, Movement } from './expected';
+export { parseMinor, validAmount, countVariance, overThreshold, closeNeedsApproval, denominationTotal, varianceText } from './register-count.helpers';
+export { denominations } from './register-count.denominations';
+export { registerSessionSchema, registerSessionCollection, cashMovementSchema, closureSchema } from './schemas';
+export type { RegisterSession, CashMovement, Closure } from './schemas';
+export {
+  mintUuid, readRegister, ensureRegister, observeRegister$, getBoundRegisterId, readBoundRegister, bindRegister,
+  unbindRegister, nextSaleCounter, mintClosureNumber, advancePerpetual,
+} from './register-document';
+export type { RegisterHost, RegisterCounters, RegisterBucket, RegisterStore, RegisterDocument } from './register-document';
+export {
+  RegisterSessionRequiredError, RegisterSessionClosedError, RegisterMovementStrandedError, openSessionSelector,
+  requireOpenSession, stampSession, openSession, startCounting, backToSelling, closeSession, recordMovement, voidMovement, writeClosure,
+} from './session-store';
+export type { RegisterSessionCollection, CashMovementCollection, ClosureCollection } from './session-store';
+export { deriveSettled } from './settled-figures';
+export type { Correction, RecordedFigures } from './settled-figures';
+export { exportCsv } from './export-csv';
+export { labelKeys } from './document-labels';
+export { clampClosureScope, selectClosureRows } from './closure-rows';
+export type { ClosureScope } from './closure-rows';
+export { minorToDecimal } from './money';
+export { formatClosureDate, buildClosureDocument, buildXReportDocument } from './closure-document';
+export type { ClosureContext } from './closure-document';
+export { registerFactsLogger, recordRegisterFact, type Actor, type RegisterFact } from './facts';
+export { useRegisterSession, RegisterTenderInProgressError, RegisterSessionAlreadyOpenError, RegisterCloseIncompleteError, RegisterApprovalRequiredError } from './use-register-session';
+export type { UseRegisterSessionOptions } from './use-register-session';

package/src/register/money.ts

@@ -0,0 +1,18 @@
+/**
+ * Minor-unit money formatting shared across the register package (moved out of `export-csv.ts` so
+ * `closure-document.ts` reuses the same implementation instead of duplicating it).
+ */
+
+/**
+ * `minor` as a fixed-point decimal string with exactly `exponent` places: `-50` at exponent 2 is
+ * `'-0.50'`, `1250` is `'12.50'`, and at exponent 0, `1500` is `'1500'`. Integer maths only —
+ * sign, `Math.trunc`, and the remainder padded to `exponent` digits — no `toFixed` on floats.
+ */
+export function minorToDecimal(minor: number, exponent: number): string {
+  const sign = minor < 0 ? '-' : '';
+  const abs = Math.abs(minor);
+  const scale = 10 ** exponent;
+  const whole = Math.trunc(abs / scale);
+  const fraction = abs % scale;
+  return exponent === 0 ? `${sign}${whole}` : `${sign}${whole}.${String(fraction).padStart(exponent, '0')}`;
+}

package/src/register/movement-input.ts

@@ -0,0 +1,59 @@
+/**
+ * A cash-movement grammar a server can enforce, mirrored on the device.
+ *
+ * The limits come from WCPOS's server, which refuses a movement whose amount is not a plain
+ * unsigned decimal string, whose integer part carries more than fifteen significant digits,
+ * whose paid in/out amount is not positive, or whose reason is blank or over 500 characters.
+ * Gating the confirm button on `Number(amount) > 0` alone let several of those through, and a
+ * refused movement is cash that has already physically moved: the row is marked permanently
+ * failed and never reaches the ledger.
+ *
+ * No amount here is ever minor units — this mirror of the server's grammar only ever sees the
+ * string the cashier typed. Port provenance and re-sync notes: ADR-032 amendment 1.
+ */
+const SERVER_DECIMAL = /^\d+(?:\.\d+)?$/;
+const MAX_INTEGER_DIGITS = 15;
+const MAX_REASON_LENGTH = 500;
+
+export type MovementType = 'paid_in' | 'paid_out' | 'no_sale';
+
+/**
+ * Rewrite what a keypad produced into the server's grammar, but only where the cashier's
+ * intent is unambiguous: a bare leading or trailing point is a half-typed number, and a comma
+ * followed by one or two digits is a decimal separator on a Spanish or German keypad.
+ *
+ * The digit count is the whole safeguard. `"1,000"` is a thousands separator to an English
+ * cashier on a hardware keyboard and a decimal to nobody, so converting it would silently
+ * record a movement of ONE — money quietly lost, which is the exact failure this module
+ * exists to prevent. Anything ambiguous is left as typed so it fails visibly instead.
+ */
+const KEYPAD_DECIMAL_COMMA = /^(\d+),(\d{1,2})$/;
+export function normalizeAmount(raw: string): string {
+  const trimmed = raw.trim();
+  const dotted = trimmed.replace(KEYPAD_DECIMAL_COMMA, '$1.$2');
+  return dotted.replace(/^\./, '0.').replace(/\.$/, '');
+}
+
+/** Whether the server's `decimal()` would accept this string. */
+export function isServerDecimal(value: string): boolean {
+  if (!SERVER_DECIMAL.test(value)) return false;
+  return value.split('.')[0].replace(/^0+/, '').length <= MAX_INTEGER_DIGITS;
+}
+
+/**
+ * The field the server would name in its 400, or null when it would accept the movement.
+ * A no sale carries no amount — the sheet sends '0' — but still needs a reason.
+ */
+export function movementFieldError(input: {
+  type: MovementType;
+  amount: string;
+  reason: string;
+}): 'amount' | 'reason' | null {
+  if (input.type !== 'no_sale') {
+    const amount = normalizeAmount(input.amount);
+    if (!isServerDecimal(amount) || Number(amount) <= 0) return 'amount';
+  }
+  const reason = input.reason.trim();
+  if (!reason || reason.length > MAX_REASON_LENGTH) return 'reason';
+  return null;
+}

package/src/register/register-count.denominations.ts

@@ -0,0 +1,11 @@
+/**
+ * Cash denominations by face value, in integer minor units, largest first (ADR-032 amendment 1:
+ * WCPOS `next` `3b5331b5c`). Every list, `default` included, assumes a two-decimal currency.
+ */
+const coinsMinor = [200, 100, 50, 20, 10, 5, 2, 1];
+export const denominations: Record<string, number[]> = {
+  GBP: [5000, 2000, 1000, 500, ...coinsMinor],
+  EUR: [50000, 20000, 10000, 5000, 2000, 1000, 500, ...coinsMinor],
+  USD: [10000, 5000, 2000, 1000, 500, 100, 25, 10, 5, 1],
+  default: [10000, 5000, 2000, 1000, 500, 200, 100, 50, 25, 10, 5, 1],
+};

package/src/register/register-count.helpers.ts

@@ -0,0 +1,64 @@
+/**
+ * The pure maths behind a register count: variance against the expected float, a display
+ * string for it, and the denomination arithmetic the counting keypad uses. Port provenance
+ * (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`.
+ *
+ * Money here is TallyUI's convention: integer minor units. Everywhere WCPOS assumed two
+ * decimals, these take the currency's `exponent` instead — 0 for JPY, 3 for KWD — except
+ * `validAmount`, which like WCPOS still takes the cashier's typed text.
+ */
+
+/**
+ * Parses a decimal string the cashier typed into integer minor units at `exponent` decimal
+ * places, without rounding. Returns `NaN` when the string carries more precision than the
+ * currency allows, so a safe-integer check on the result also rejects it.
+ */
+export function parseMinor(text: string, exponent: number): number {
+  const [whole, fraction = ''] = text.trim().split('.');
+  if (fraction.length > exponent) return NaN;
+  return Number(whole || '0') * 10 ** exponent + Number(fraction.padEnd(exponent, '0') || '0');
+}
+
+export const validAmount = (value: string, exponent: number) =>
+  /^(?:\d+\.?\d*|\.\d+)$/.test(value) &&
+  Number.isFinite(Number(value)) &&
+  Number.isSafeInteger(parseMinor(value, exponent));
+
+/** Counted minus expected, both already in minor units. */
+export const countVariance = (countedMinor: number, expectedMinor: number) =>
+  countedMinor - expectedMinor;
+
+/** Whether the variance exceeds the store's configured threshold (minor units; none means never). */
+export const overThreshold = (variance: number, thresholdMinor?: number | null) =>
+  thresholdMinor != null && Math.abs(variance) > thresholdMinor;
+
+/**
+ * Whether a close's cash count needs a manager's approval: its cash variance against the expected
+ * cash is over the threshold. The one definition `RegisterCount` and `useRegisterSession`'s
+ * `closeSession` gate share (ADR-032).
+ */
+export const closeNeedsApproval = (countedCashMinor: number, expectedCashMinor: number, thresholdMinor?: number | null) =>
+  overThreshold(countVariance(countedCashMinor, expectedCashMinor), thresholdMinor);
+
+/** Sums denomination face values (already minor units) by piece count. */
+export const denominationTotal = (pieces: Record<number, number>) =>
+  Object.entries(pieces).reduce((sum, [value, count]) => sum + Number(value) * count, 0);
+
+/**
+ * The variance line under the count: exact, short or over. `format` takes a major-unit
+ * amount, as an app's currency formatter expects, so `exponent` converts `variance` back for
+ * it; `t` supplies the translated words for the `register.exact`/`register.short`/
+ * `register.over` keys. Both are the app's own — neutral here.
+ *
+ * The direction lives in the word, not a sign (the Front desk, 2026-09-28): a signed amount
+ * next to "short" read as a double negative, so the amount here is always its absolute value.
+ */
+export function varianceText(
+  variance: number,
+  exponent: number,
+  format: (value: number) => string,
+  t: (key: string) => string,
+) {
+  if (!variance) return t('register.exact');
+  return `${format(Math.abs(variance) / 10 ** exponent)} ${t(variance < 0 ? 'register.short' : 'register.over')}`;
+}