@tallyui/pos 0.1.0 → 2.0.0

package/src/order/order-manager.ts

@@ -8,7 +8,7 @@ export interface ParkedOrderSummary {
   id: string;
   customerName?: string;
   itemCount: number;
-  total: number;
+  totalMinor: number;
   parkedAt: string;
   source: 'local' | 'server';
 }
@@ -29,7 +29,8 @@ export interface OrderManager {
 }
 
 export function createOrderManager(options: OrderManagerOptions): OrderManager {
-  const { currency, taxContext, draftsCollection } = options;
+  const { taxContext, draftsCollection } = options;
+  const currency = options.currency.toUpperCase();
 
   let activeBuilder = createOrderBuilder({ currency, taxContext });
   const activeSubject = new BehaviorSubject<OrderBuilder>(activeBuilder);
@@ -42,7 +43,7 @@ export function createOrderManager(options: OrderManagerOptions): OrderManager {
           id: json.id,
           customerName: json.customerName || undefined,
           itemCount: json.itemCount ?? 0,
-          total: json.total ?? 0,
+          totalMinor: json.total ?? 0,
           parkedAt: json.parkedAt ?? '',
           source: 'local' as const,
         };
@@ -67,7 +68,7 @@ export function createOrderManager(options: OrderManagerOptions): OrderManager {
         data: JSON.stringify(snapshot),
         customerName: snapshot.customer?.name ?? '',
         itemCount: snapshot.lineItems.length,
-        total: snapshot.total,
+        total: snapshot.totalMinor,
         parkedAt: new Date().toISOString(),
       });
 
@@ -97,47 +98,25 @@ export function createOrderManager(options: OrderManagerOptions): OrderManager {
         builder.setNote(savedOrder.note);
       }
 
-      // Restore line items using synthetic traits
+      // Restore line items and their discounts
       for (const line of savedOrder.lineItems) {
-        const syntheticTraits = {
-          getId: (d: any) => d.productId,
-          getName: (d: any) => d.name,
-          getSku: (d: any) => d.sku,
-          getPrice: (d: any) => String(d.price),
-          getRegularPrice: (d: any) => String(d.price),
-          getSalePrice: () => undefined,
-          isOnSale: () => false,
-          getImageUrl: (d: any) => d.imageUrl,
-          getImageUrls: (d: any) => (d.imageUrl ? [d.imageUrl] : []),
-          getDescription: () => undefined,
-          getStockStatus: () => 'instock' as const,
-          getStockQuantity: () => null,
-          hasVariants: () => false,
-          getType: () => 'simple',
-          getBarcode: () => undefined,
-          getCategoryNames: () => [],
-        };
-        builder.addProduct(line, syntheticTraits, {
+        const lineId = builder.addLine({
+          productId: line.productId,
           variantId: line.variantId,
+          name: line.name,
+          sku: line.sku,
+          imageUrl: line.imageUrl,
+          unitPrice: { amount: line.unitPriceMinor, currency, taxInclusive: line.taxInclusive },
           quantity: line.quantity,
+          taxRates: line.taxLines.map(({ code, ratePpm }) => ({ code, ratePpm })),
         });
-      }
-
-      // Restore line-level discounts
-      const resumedOrder = builder.getSnapshot();
-      for (const savedLine of savedOrder.lineItems) {
-        const newLine = resumedOrder.lineItems.find(
-          (li) => li.productId === savedLine.productId && li.variantId === savedLine.variantId,
-        );
-        if (newLine) {
-          for (const discount of savedLine.discounts) {
-            builder.applyLineDiscount(newLine.id, {
-              type: discount.type,
-              value: discount.value,
-              label: discount.label,
-              couponCode: discount.couponCode,
-            });
-          }
+        for (const discount of line.discounts) {
+          builder.applyLineDiscount(lineId, {
+            type: discount.type,
+            value: discount.value,
+            label: discount.label,
+            couponCode: discount.couponCode,
+          });
         }
       }
 
@@ -155,7 +134,9 @@ export function createOrderManager(options: OrderManagerOptions): OrderManager {
       for (const payment of savedOrder.payments) {
         builder.addPayment({
           method: payment.method,
-          amount: payment.amount,
+          amountMinor: payment.amountMinor,
+          tenderedMinor: payment.tenderedMinor,
+          changeMinor: payment.changeMinor,
           reference: payment.reference,
         });
       }

package/src/order/types.ts

@@ -1,3 +1,5 @@
+import type { Money } from '@tallyui/core';
+
 export interface Order {
   id: string;
   status: 'draft' | 'parked' | 'saved' | 'completed';
@@ -6,17 +8,42 @@ export interface Order {
   payments: Payment[];
   customer: CustomerSummary | null;
   note: string;
-  subtotal: number;
-  discountTotal: number;
-  taxTotal: number;
-  total: number;
-  balanceDue: number;
-  changeDue: number;
   currency: string;
+  pricesIncludeTax: boolean;
+  // Settlement figures, sent in `order.create` (ADR-038, ADR-062). Show `display` instead (ADR-063).
+  subtotalMinor: number;      // settlement: excl. tax, after line and order discounts (both pre-tax, ADR-062)
+  discountMinor: number;      // settlement: Σ lineItems[].discountMinor, each in its line's own mode, so it mixes modes; not for display
+  taxMinor: number;           // settlement: rounded once per order
+  totalMinor: number;         // settlement: what the customer pays
+  display: DisplayTotals;
+  paidMinor: number;
+  balanceDueMinor: number;    // max(0, total − paid)
+  changeDueMinor: number;     // max(0, paid − total)
   createdAt: string;
   updatedAt: string;
 }
 
+/**
+ * Figures for showing the cart or a receipt in the store's display mode (ADR-063); never sent to the server.
+ * A parked order's saved draft may carry them; they are recomputed from the lines on resume, so never authoritative.
+ */
+export interface DisplayTotals {
+  taxInclusive: boolean;      // = order.pricesIncludeTax
+  subtotalMinor: number;      // before discounts: total − tax + discount when exclusive, total + discount when inclusive
+  discountMinor: number;      // Σ lines' discount rows + orderDiscountMinor, in the display mode; >= 0
+  taxMinor: number;           // = order.taxMinor (added when exclusive, included when inclusive)
+  totalMinor: number;         // = order.totalMinor
+  lines: DisplayLine[];       // in lineItems order; Σ amountMinor = subtotalMinor
+  orderDiscountMinor: number; // the order discounts as one row, not allocated: Σ each line's share, converted on its own
+}
+
+/** One line in the display mode (ADR-063): before any discount, with its own discounts as sub-rows. */
+export interface DisplayLine {
+  lineId: string;
+  amountMinor: number;        // quantity × unit price in the display mode; the last converted line also carries the rounding residue
+  discounts: { discountId: string; label?: string; amountMinor: number }[]; // this line's own discounts, each converted on its own
+}
+
 export interface LineItem {
   id: string;
   productId: string;
@@ -24,31 +51,45 @@ export interface LineItem {
   name: string;
   sku: string;
   imageUrl?: string;
-  price: number;
-  quantity: number;
-  taxRate: number;
-  taxAmount: number;
+  unitPriceMinor: number;     // as sold, integer
+  quantity: number;           // integer >= 1
+  taxLines: LineTaxLine[];    // stacked rates on the same net base (ADR-040)
   discounts: AppliedDiscount[];
-  discountAmount: number;
-  lineTotal: number;
+  discountMinor: number;      // line discounts + orderDiscountMinor, in the line's own mode
+  orderDiscountMinor: number; // this line's allocated share of the order discounts (ADR-062)
+  netMinor: number;           // unitPriceMinor × quantity − discountMinor; the taxed base
+  taxMicros: string;          // Σ taxLines[].taxMicros, decimal string of a bigint
+  taxInclusive: boolean;      // the price's own tax mode; the order's when the price has none
+  /** Set only when the price's tax mode differs from the order's; named price mode → order mode. */
+  priceTaxModeConverted?: 'inclusive-to-exclusive' | 'exclusive-to-inclusive';
+}
+
+export interface LineTaxLine {
+  code?: string;
+  ratePpm: number;
+  taxMicros: string;          // exact, decimal string of a bigint
 }
 
 export interface Discount {
   type: 'percentage' | 'fixed';
-  value: number;
+  value: number;              // percentage: percent (e.g. 10); fixed: integer minor units
   label?: string;
   couponCode?: string;
 }
 
 export interface AppliedDiscount extends Discount {
   id: string;
-  amount: number;
+  amountMinor: number;        // an order discount: its own-mode amount, allocated across the lines
 }
 
 export interface Payment {
   id: string;
   method: string;
-  amount: number;
+  // For cash, record the full amount tendered here, not the capped amount: `finalizeOrder`
+  // caps it at the balance due and writes out `tenderedMinor`/`changeMinor` itself.
+  amountMinor: number;
+  tenderedMinor?: number;
+  changeMinor?: number;
   reference?: string;
 }
 
@@ -64,3 +105,14 @@ export interface PaymentMethod {
   icon?: string;
   requiresReference?: boolean;
 }
+
+export interface AddLineInput {
+  productId: string;
+  variantId?: string;
+  name: string;
+  sku?: string;
+  imageUrl?: string;
+  unitPrice: Money & { taxInclusive?: boolean }; // currency must equal the order currency; taxInclusive wins over the order's pricesIncludeTax
+  quantity?: number;          // default 1
+  taxRates?: Array<{ code?: string; ratePpm: number }>; // default: [{ ratePpm: from taxContext }]
+}

package/src/outbox/http-transport.ts

@@ -0,0 +1,66 @@
+import { COMMANDS_PATH, PROTOCOL_HEADER, PROTOCOL_VERSION, isCommandBatchResponse } from '@tallyui/core';
+import type { CommandTransport } from './types';
+
+// These HTTP statuses permanently refuse the entire command batch.
+const PERMANENT_STATUSES = new Set([400, 403, 413, 415, 422]);
+
+export interface HttpTransportOptions {
+  baseUrl: string;
+  getHeaders: () => Record<string, string> | Promise<Record<string, string>>;
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+}
+
+export function createHttpCommandTransport(options: HttpTransportOptions): CommandTransport {
+  const fetch = options.fetch ?? globalThis.fetch;
+  let end = options.baseUrl.length;
+  while (end > 0 && options.baseUrl[end - 1] === '/') {
+    end--;
+  }
+  const baseUrl = options.baseUrl.slice(0, end);
+  return {
+    async send(batch) {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 30000);
+      try {
+        const response = await fetch(`${baseUrl}${COMMANDS_PATH}`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            [PROTOCOL_HEADER]: String(PROTOCOL_VERSION),
+            ...await options.getHeaders(),
+          },
+          body: JSON.stringify({ commands: batch }),
+          signal: controller.signal,
+        });
+        const retryAfter = response.headers.get('Retry-After');
+        const seconds = retryAfter === null ? NaN : Number(retryAfter);
+        const retry = (reason: string) => ({ kind: 'retry' as const, reason,
+          ...(Number.isFinite(seconds) && seconds >= 0 ? { retryAfterMs: seconds * 1000 } : {}),
+        });
+        if (response.status === 401) return { kind: 'unauthorized' };
+        if (PERMANENT_STATUSES.has(response.status)) {
+          let reason = `status_${response.status}`;
+          try {
+            const body = await response.json();
+            if (typeof body?.message === 'string') reason = body.message;
+            else if (typeof body?.code === 'string') reason = body.code;
+          } catch {}
+          return { kind: 'refused', status: response.status, reason };
+        }
+        if (response.status !== 200) return retry(`status_${response.status}`);
+        let body: unknown;
+        try {
+          body = await response.json();
+        } catch {
+          return retry(controller.signal.aborted ? 'network' : 'bad_body');
+        }
+        return isCommandBatchResponse(body) ? { kind: 'results', results: body.results } : retry('bad_body');
+      } catch {
+        return { kind: 'retry', reason: 'network' };
+      } finally {
+        clearTimeout(timeout);
+      }
+    },
+  };
+}

package/src/outbox/index.ts

@@ -0,0 +1,7 @@
+export { createHttpCommandTransport } from './http-transport';
+export type { HttpTransportOptions } from './http-transport';
+export { createOrderOutbox } from './order-outbox';
+export type { OrderOutboxOptions, OrderOutbox } from './order-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

@@ -0,0 +1,198 @@
+import type { RxCollection } from 'rxdb';
+import { BehaviorSubject, type Observable, type Subscription } from 'rxjs';
+import { toOrderCreateEnvelope, uuidv7, type PosOrder } from '../pos-order';
+import { countFresh, readFresh } from '../rxdb';
+import type { CommandTransport, OutboxState } from './types';
+
+// Pause after three 401s since the server last accepted credentials.
+const AUTH_FAILURES_BEFORE_PROMPT = 3;
+
+// Rejections that may hide an order the server already created: resending under a new
+// command id could duplicate it, so requeue() leaves these for manual reconciliation.
+const NOT_REQUEUEABLE = new Set(['idempotency_mismatch']);
+
+export interface OrderOutboxOptions {
+  collection: RxCollection<PosOrder>;
+  transport: CommandTransport;
+  deviceId: string;
+  batchSize?: number;
+  initialBackoffMs?: number;
+  maxBackoffMs?: number;
+  random?: () => number;
+  now?: () => number;
+}
+
+export interface OrderOutbox {
+  /** Sends pending orders until empty or retrying. Concurrent calls share one run. */
+  flush(): Promise<void>;
+  /** Moves rejected orders (all, or those whose id is listed) back to pending with a new commandId, then flushes.
+   * Orders rejected with idempotency_mismatch are left for reconciliation. Resolves to the number requeued. */
+  requeue(orderIds?: string[]): Promise<number>;
+  /** Watches for pending orders and sends them. */
+  start(): void;
+  /** Stops watching and retrying. */
+  stop(): void;
+  state$: Observable<OutboxState>;
+}
+
+export function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox {
+  const { collection, transport, deviceId } = options;
+  const batchSize = Math.min(options.batchSize ?? 10, 10);
+  const initialBackoff = options.initialBackoffMs ?? 1000;
+  const maxBackoff = options.maxBackoffMs ?? 60000;
+  const random = options.random ?? Math.random;
+  const now = options.now ?? Date.now;
+  const state$ = new BehaviorSubject<OutboxState>({ pending: 0, sending: false });
+  const attempts = new Map<string, number>();
+  let backoff = initialBackoff;
+  let unauthorizedSinceAccepted = 0;
+  let running: Promise<void> | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let subscription: Subscription | undefined;
+  let stopped = false;
+  let insertedDuringRun = false;
+  let stoppedDuringRun = false;
+
+  // Every read goes past RxDB's query cache: in RxDB 16.21.1 a sale inserted while a cached
+  // query's read is in flight never reaches that query, and stayed unsent until a restart.
+  async function updateState(patch: Partial<OutboxState> = {}) {
+    const pending = await countFresh(collection, { syncStatus: 'pending' });
+    state$.next({ ...state$.value, ...patch, pending });
+  }
+
+  function scheduleRetry(reason: string, retryAfterMs = 0) {
+    state$.next({ ...state$.value, lastRetryReason: reason });
+    if (stopped) { stoppedDuringRun = true; return; }
+    const delay = Math.min(Math.max(retryAfterMs, backoff * (0.9 + 0.2 * random())), maxBackoff);
+    backoff = Math.min(backoff * 2, maxBackoff);
+    timer = setTimeout(() => { timer = undefined; flush().catch(() => {}); }, delay);
+    state$.next({ ...state$.value, sending: false, nextAttemptAt: now() + delay });
+  }
+
+  async function run() {
+    stoppedDuringRun = false;
+    while (!stopped) try {
+      await updateState({ sending: true, nextAttemptAt: undefined });
+      insertedDuringRun = false;
+      const orders = await readFresh(collection, {
+        selector: { syncStatus: 'pending' }, sort: [{ createdAt: 'asc' }], limit: batchSize,
+      });
+      if (!orders.length || stopped) { stoppedDuringRun = stopped; return; }
+      const batch = orders.map((order) => {
+        const attempt = (attempts.get(order.commandId) ?? 0) + 1;
+        attempts.set(order.commandId, attempt);
+        return toOrderCreateEnvelope(order, deviceId, attempt);
+      });
+      const outcome = await transport.send(batch);
+      if (outcome.kind === 'retry') {
+        return scheduleRetry(outcome.reason, outcome.retryAfterMs);
+      }
+      if (outcome.kind === 'unauthorized') {
+        unauthorizedSinceAccepted++;
+        if (unauthorizedSinceAccepted < AUTH_FAILURES_BEFORE_PROMPT) return scheduleRetry('unauthorized');
+        state$.next({ ...state$.value, authRequired: true, lastRetryReason: 'unauthorized',
+          sending: false, nextAttemptAt: undefined });
+        return;
+      }
+      if (outcome.kind === 'refused') {
+        unauthorizedSinceAccepted = 0;
+        state$.next({ ...state$.value, refused: { status: outcome.status, reason: outcome.reason },
+          authRequired: false, lastRetryReason: 'refused', sending: false, nextAttemptAt: undefined });
+        return;
+      }
+      unauthorizedSinceAccepted = 0;
+      state$.next({ ...state$.value, authRequired: false, refused: undefined });
+      let progressed = false;
+      for (const order of orders) {
+        const result = outcome.results.find((entry) => entry.id === order.commandId);
+        if (!result) continue;
+        // A primary-key lookup straight on the storage instance: skips the query cache (like
+        // readFresh, but without its full index scan here) and excludes a deleted document as not
+        // found. The commandId check catches an order requeued while this one was in flight.
+        const [stored] = await collection.storageInstance.findDocumentsById([order.id], false);
+        if (stored?.syncStatus !== 'pending' || stored.commandId !== order.commandId) continue;
+        const current = await collection.findOne(order.id).exec();
+        if (!current) continue;
+        const updatedAt = new Date(now()).toISOString();
+        await current.incrementalPatch(result.status === 'rejected'
+          ? { syncStatus: 'rejected', error: result.error, updatedAt }
+          : { syncStatus: 'applied', serverRefs: result.serverRefs,
+            ...(result.warnings ? { warnings: result.warnings } : {}), updatedAt });
+        attempts.delete(order.commandId);
+        progressed = true;
+        await updateState();
+      }
+      if (!progressed) return scheduleRetry('no_progress');
+      backoff = initialBackoff;
+      state$.next({ ...state$.value, lastRetryReason: undefined });
+    } catch (error) {
+      scheduleRetry('error: ' + (error instanceof Error ? error.message : String(error)));
+      return;
+    }
+    stoppedDuringRun = true;
+  }
+
+  function flush(): Promise<void> {
+    if (running) return running;
+    stopped = false;
+    clearTimeout(timer);
+    timer = undefined;
+    running = Promise.resolve().then(run).finally(async () => {
+      try { await updateState({ sending: false }); } catch {}
+      running = undefined;
+      if ((insertedDuringRun || stoppedDuringRun) && !stopped && timer === undefined) flush().catch(() => {});
+    });
+    return running;
+  }
+
+  updateState().catch(() => {});
+  return {
+    state$,
+    flush,
+    async requeue(orderIds) {
+      const orders = (await readFresh(collection, { selector: { syncStatus: 'rejected',
+        ...(orderIds ? { id: { $in: orderIds } } : {}) } }))
+        .filter((order) => !NOT_REQUEUEABLE.has(order.error?.code ?? ''));
+      let count = 0;
+      for (const order of orders) {
+        const oldCommandId = order.commandId;
+        let changed = false;
+        // The modifier sees the stored state, even when findOne's cached result is stale.
+        await (await collection.findOne(order.id).exec())?.incrementalModify((data) => {
+          changed = data.syncStatus === 'rejected' && !NOT_REQUEUEABLE.has(data.error?.code ?? '');
+          if (!changed) return data;
+          data.syncStatus = 'pending';
+          delete data.error;
+          // The server ledger stored the rejection under the old id; replaying it returns that rejection.
+          // For the codes requeue() accepts, the server created no order, so a fresh id cannot duplicate one.
+          data.commandId = uuidv7();
+          data.updatedAt = new Date(now()).toISOString();
+          return data;
+        });
+        if (changed) { count++; attempts.delete(oldCommandId); }
+      }
+      await updateState();
+      if (count && !stopped) flush().catch(() => {});
+      return count;
+    },
+    start() {
+      stopped = false;
+      if (!subscription) subscription = collection.$.subscribe((event) => {
+        if (event.documentData?.syncStatus === 'pending' &&
+          (event.operation === 'INSERT' || event.operation === 'UPDATE')) {
+          insertedDuringRun = true;
+          flush().catch(() => {});
+        }
+      });
+      if (!stopped) flush().catch(() => {});
+    },
+    stop() {
+      stopped = true;
+      clearTimeout(timer);
+      timer = undefined;
+      subscription?.unsubscribe();
+      subscription = undefined;
+      state$.next({ ...state$.value, nextAttemptAt: undefined });
+    },
+  };
+}

package/src/outbox/types.ts

@@ -0,0 +1,22 @@
+import type { CommandEnvelope, CommandResult, OrderCreatePayload } from '@tallyui/core';
+
+export type TransportOutcome =
+  | { kind: 'results'; results: CommandResult[] }
+  | { kind: 'unauthorized' }
+  | { kind: 'refused'; status: number; reason: string }
+  | { kind: 'retry'; reason: string; retryAfterMs?: number };
+
+export interface CommandTransport {
+  send(batch: CommandEnvelope<OrderCreatePayload>[]): Promise<TransportOutcome>;
+}
+
+export interface OutboxState {
+  pending: number;
+  sending: boolean;
+  lastRetryReason?: string;
+  nextAttemptAt?: number;
+  /** Set after 3 consecutive 401s; the app should ask the cashier to sign in, then call flush(). */
+  authRequired?: boolean;
+  /** Set when the server refused a whole batch (HTTP 400, 403, 413, 415, 422). No order is changed; sending pauses until the next flush(). */
+  refused?: { status: number; reason: string };
+}