@tallyui/pos 0.1.0 → 3.0.0-next.0

package/src/order/types.ts

@@ -1,3 +1,5 @@
+import type { Money, TaxRounding } from '@tallyui/core';
+
 export interface Order {
   id: string;
   status: 'draft' | 'parked' | 'saved' | 'completed';
@@ -6,17 +8,47 @@ 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;
+  /** The store's tax rounding strategy the figures were computed with (#287), from the sale's tax context; absent is per_order. */
+  taxRounding?: TaxRounding;
+  // 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, unless taxRounding says otherwise (#287)
+  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;
 }
 
+/** An Order as it was stored and sent, whose customer id may have been left out. */
+export type SentOrder = Omit<Order, 'customer'> & { customer: (Omit<CustomerSummary, 'id'> & { id?: string }) | null };
+
+/**
+ * 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 +56,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 +110,15 @@ 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: taxContext's rate for taxClass }]
+  taxClass?: string;          // the product's tax class (ProductTraits.getTaxClass); ignored when taxRates is given
+}

package/src/outbox/backend-not-found.ts

@@ -0,0 +1,27 @@
+import { BehaviorSubject, type Observable } from 'rxjs';
+import type { OutboxState, TransportOutcome } from './types';
+
+// Consecutive 404 answers before backendMissing tells the cashier; fewer may be a deploy blip.
+const NOT_FOUND_BEFORE_NOTICE = 3;
+
+/** Counts consecutive 404s across every outbox given it, so a missing plugin shows once, whichever outbox meets it. */
+export interface BackendNotFound {
+  /** A 404 counts; any other answer from the store clears; offline (`network`) changes nothing. */
+  record(outcome: TransportOutcome, at: number): void;
+  backendMissing$: Observable<OutboxState['backendMissing']>;
+}
+
+export function createBackendNotFound(): BackendNotFound {
+  let count = 0;
+  let since = 0; // when the first of the consecutive 404s arrived
+  const backendMissing$ = new BehaviorSubject<OutboxState['backendMissing']>(undefined);
+  return {
+    backendMissing$,
+    record(outcome, at) {
+      if (outcome.kind === 'retry' && outcome.reason === 'network') return;
+      if (outcome.kind === 'retry' && outcome.reason === 'status_404') { if (count++ === 0) since = at; } else count = 0;
+      const missing = count >= NOT_FOUND_BEFORE_NOTICE;
+      if (missing !== !!backendMissing$.value) backendMissing$.next(missing ? { since } : undefined);
+    },
+  };
+}

package/src/outbox/http-transport.ts

@@ -0,0 +1,67 @@
+import { COMMANDS_PATH, PROTOCOL_HEADER, PROTOCOL_VERSION, isCommandBatchResponse, type AnyCommandEnvelope } 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<AnyCommandEnvelope> {
+  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 ? 'timeout' : 'bad_body');
+        }
+        return isCommandBatchResponse(body) ? { kind: 'results', results: body.results } : retry('bad_body');
+      } catch {
+        // `timeout`: sent, but no answer within the deadline. `network`: the store could not be reached.
+        return { kind: 'retry', reason: controller.signal.aborted ? 'timeout' : 'network' };
+      } finally {
+        clearTimeout(timeout);
+      }
+    },
+  };
+}

package/src/outbox/index.ts

@@ -0,0 +1,9 @@
+export { createHttpCommandTransport } from './http-transport';
+export type { HttpTransportOptions } from './http-transport';
+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 type { TransportOutcome, CommandTransport, OutboxState } from './types';
+export { useOrderOutbox, outboxLogger } from './use-order-outbox';
+export type { UseOrderOutboxOptions, UseOrderOutboxResult } from './use-order-outbox';

package/src/outbox/logger.ts

@@ -0,0 +1,3 @@
+import { createLogger } from '../logging';
+
+export const outboxLogger = createLogger('outbox');