@tallyui/pos 0.1.0 → 3.0.0-next.0

package/src/pos-order/command.ts

@@ -0,0 +1,123 @@
+import type { OrderCreateEnvelope } from '@tallyui/core';
+import { MICROS_PER_MINOR, roundMicrosToMinor, taxMicros } from '../tax/exact';
+import type { PosOrder, PosOrderLine } from './types';
+
+export class UnsupportedOrderVersionError extends Error {
+  readonly code = 'UNSUPPORTED_ORDER_VERSION';
+  constructor(readonly needed: number, readonly supported: number) {
+    super(`This sale needs order.create version ${needed}; the server supports up to ${supported}.`);
+    this.name = 'UnsupportedOrderVersionError';
+  }
+}
+
+/**
+ * `@tallyui/core/server`'s `payloadBoundErrors` bound, in UTF-16 code units (`String.length`), on
+ * every order.create string but `customer.email` (254), `customerId` (64) and `sessionId` (36).
+ */
+export const PAYLOAD_STRING_MAX = 255;
+
+/** A non-empty string of at most `max` UTF-16 units with no NUL: what order.create's shape check accepts. */
+export const sendable = (value: unknown, max: number): value is string =>
+  typeof value === 'string' && value.length > 0 && value.length <= max && !value.includes('\u0000');
+
+/**
+ * Why a customer (picked from a search, or restored from a parked order) can't go on a sale, or null: its email
+ * (over 254 units, or a NUL) or its id (over 64, or a NUL) would be refused by order.create's shape check.
+ */
+export function customerRefusal(customer: { id?: string; email?: string }): string | null {
+  return customer.email !== undefined && customer.email !== '' && !sendable(customer.email, 254) ? CUSTOMER_REFUSALS[0]
+    : customer.id !== undefined && customer.id !== '' && !sendable(customer.id, 64) ? CUSTOMER_REFUSALS[1] : null;
+}
+/** Every message `customerRefusal` returns (email, then id). */
+export const CUSTOMER_REFUSALS = (['email', 'id'] as const)
+  .map((field) => `This customer's ${field} can't be sent to the store, so they weren't added to the sale.`);
+
+/** Text with NUL stripped, and over `max` UTF-16 units cut to `max - 1` plus '…', never inside a surrogate pair. */
+export function cutText(text: string, max: number): string {
+  const clean = text.replaceAll('\u0000', '');
+  if (clean.length <= max) return clean;
+  const high = clean.charCodeAt(max - 2);
+  return `${clean.slice(0, high >= 0xd800 && high <= 0xdbff ? max - 2 : max - 1)}…`;
+}
+
+/**
+ * Version 4 (#286): a line's discount made tax-exclusive. An exclusive line's is unchanged; an inclusive line's
+ * gross discount D on its amount A becomes `net(A) − net(A − D)`, exact in millionths (net(A − D) from its stored
+ * taxLines, the tax on A − D; net(A) from `taxMicros`, as the builder taxes), rounded half away from zero.
+ */
+function netDiscountMinor(line: PosOrderLine, pricesIncludeTax: boolean): number {
+  if (!(line.taxInclusive ?? pricesIncludeTax) || line.discountMinor === 0) return line.discountMinor;
+  const ratePpm = line.taxLines.reduce((sum, tax) => sum + tax.ratePpm, 0);
+  const taxAfter = line.taxLines.reduce((sum, tax) => sum + BigInt(tax.taxMicros), 0n);
+  const taxBefore = taxMicros(line.unitPriceMinor * line.quantity, ratePpm, true);
+  return roundMicrosToMinor(BigInt(line.discountMinor) * MICROS_PER_MINOR - taxBefore + taxAfter);
+}
+
+/**
+ * The order.create version an order's stored content makes: 3 with ADR-065's figures, else 2 when its lines are
+ * discounted (ADR-062), else 1. The builder's, and pos_orders v5's migration's for a row with no `sentVersion`.
+ */
+export function contentVersion(order: Pick<PosOrder, 'display' | 'taxByRate' | 'lines'>): 1 | 2 | 3 {
+  return order.display && order.taxByRate ? 3 : order.lines.reduce((sum, line) => sum + line.discountMinor, 0) > 0 ? 2 : 1;
+}
+
+/**
+ * Builds the ADR-038 order.create envelope for a PosOrder. It sends the stored order unchanged, so every resend of
+ * an order is byte-identical, and an order stored by an older till goes out exactly as that till sent it:
+ * `finalizeOrder` freezes the sent form (names and labels cut, an unsendable customer email or id left out).
+ * ADR-065's figures make version 3; otherwise a discounted order is version 2 (ADR-062), else version 1, byte-identical.
+ * A version-3 order goes as version 4 (#286) only when `maxVersion` is at least 4 and its `sentVersion` doesn't cap it.
+ */
+export function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attempt = 1,
+  options?: { maxVersion?: number }): OrderCreateEnvelope {
+  const grossMinor = order.lines.reduce((sum, line) => sum + line.discountMinor, 0);
+  const content = contentVersion(order);
+  const cap = options?.maxVersion === undefined ? order.sentVersion : Math.min(options.maxVersion, order.sentVersion ?? options.maxVersion);
+  if (grossMinor > 0 && cap !== undefined && cap < 2) throw new UnsupportedOrderVersionError(2, cap);
+  // Version 4 only when the cap allows it (the server advertises 4, and no sentVersion holds the order lower).
+  const version = (content === 3 && cap !== undefined && cap >= 4 ? 4
+    : Math.min(content, cap ?? content)) as OrderCreateEnvelope['version'];
+  const lineDiscounts = order.lines.map((line) => version === 4 ? netDiscountMinor(line, order.pricesIncludeTax) : line.discountMinor);
+  // The order's discount is the sum of its lines', on one basis, so the payload's two always agree.
+  const discountMinor = lineDiscounts.reduce((sum, discount) => sum + discount, 0);
+  const email = order.customer?.email;
+  const id = order.customer?.id;
+  // These are the pre-#222 customerId and sessionId checks, kept byte-exact so stored orders resend older tills' bytes; don't replace with sendable.
+  const customerId = typeof id === 'string' && id.length > 0 && id.length <= 64 ? id : undefined;
+  const sessionId = order.sessionId ?? order.lateSessionId;
+  return {
+    id: order.commandId, type: 'order.create', version, createdAt: order.createdAt, deviceId, attempt,
+    payload: {
+      clientOrderId: order.id, createdAt: order.createdAt, currency: order.currency, pricesIncludeTax: order.pricesIncludeTax,
+      lines: order.lines.map((line, i) => ({
+        clientLineId: line.id, variantId: line.variantId ?? line.productId, title: line.name,
+        quantity: line.quantity, unitPriceMinor: line.unitPriceMinor,
+        ...(line.taxInclusive !== undefined ? { taxInclusive: line.taxInclusive } : {}),
+        ...(lineDiscounts[i] > 0 ? { discountMinor: lineDiscounts[i] } : {}),
+      })),
+      payments: order.payments.map((payment) => ({
+        clientPaymentId: payment.id, method: payment.method, amountMinor: payment.amountMinor,
+        ...(payment.tenderedMinor !== undefined ? { tenderedMinor: payment.tenderedMinor } : {}),
+        ...(payment.changeMinor !== undefined ? { changeMinor: payment.changeMinor } : {}),
+        ...(payment.reference !== undefined ? { reference: payment.reference } : {}),
+      })),
+      subtotalMinor: order.subtotalMinor,
+      ...(discountMinor > 0 ? { discountMinor } : {}),
+      taxMinor: order.taxMinor, totalMinor: order.totalMinor,
+      ...(version >= 3 ? {
+        display: { ...order.display!, lines: order.display!.lines.map(({ lineId, amountMinor, discounts }) => ({
+          clientLineId: lineId, amountMinor, discounts,
+        })) },
+        taxByRate: order.taxByRate!.map(({ ratePpm, code, netMinor, amountMinor, grossMinor }) => ({
+          ratePpm, ...(code !== undefined ? { code } : {}), netMinor, taxMinor: amountMinor, grossMinor,
+        })),
+      } : {}),
+      customer: version >= 3
+        ? (email || customerId ? { ...(email ? { email } : {}), ...(customerId ? { customerId } : {}) } : null)
+        : (email ? { email } : null),
+      ...(order.registerId !== undefined ? { registerId: order.registerId } : {}),
+      ...(order.cashierRef !== undefined ? { cashierRef: order.cashierRef } : {}),
+      ...(version >= 3 && typeof sessionId === 'string' && sessionId.length > 0 && sessionId.length <= 36 ? { sessionId } : {}),
+    },
+  };
+}

package/src/pos-order/device-id.ts

@@ -0,0 +1,23 @@
+import { uuidv7 } from './uuidv7';
+
+/** The device id used when no storage is available, shared by every caller in this process. */
+let processId: string | undefined;
+
+/**
+ * Returns this device's id (a UUIDv7), stored under `key` in `storage` (web storage, or an app's
+ * equivalent) and minted on first use; medusapos passes `'medusapos.register_id'`. With no storage,
+ * or one that throws on read or write, it falls back to one id per process.
+ */
+export function getDeviceId(storage: { getItem(key: string): string | null; setItem(key: string, value: string): void } | null,
+  key: string): string {
+  try {
+    if (storage) {
+      const existing = storage.getItem(key);
+      if (existing) return existing;
+      const id = uuidv7();
+      storage.setItem(key, id);
+      return id;
+    }
+  } catch { /* Use the process id when web storage is unavailable. */ }
+  return processId ??= uuidv7();
+}

package/src/pos-order/finalize.ts

@@ -0,0 +1,219 @@
+import { minorUnitDigits, type ServerCapabilities, type TaxRounding } from '@tallyui/core';
+import type { Order, SentOrder } from '../order/types';
+import { DEFAULT_TAX_ROUNDING, taxLinesByRate } from '../tax/exact';
+import { outboxLogger } from '../outbox/logger';
+import { cutText, PAYLOAD_STRING_MAX, sendable } from './command';
+import type { PosOrder, PosOrderLocalWarning, PosOrderPayment } from './types';
+import { uuidv7 } from './uuidv7';
+
+export interface FinalizeOptions {
+  localWarnings?: PosOrderLocalWarning[];
+  registerId?: string;
+  // No `sessionId`: `stampSession` is the only way to set a sale's session, because it checks the
+  // session is live. Tests and migrations that need a stamped order spread `{ ...order, sessionId }`.
+  cashierRef?: string;
+  now?: Date;
+  /** Tests only: replaces uuidv7. Every id it returns must be at most 255 characters with no NUL (order.create's bound). */
+  newId?: () => string;
+  /** The store's `order.create` capability (ADR-062); `undefined` is treated as 1. */
+  capabilities?: ServerCapabilities;
+}
+
+/** A line name in a refusal message: 60 UTF-16 units of it plus '…' at most, so a cashier-facing message stays short. */
+export const MESSAGE_NAME_MAX = 61;
+
+/** The receipt shows the order as it was stored and sent (Front desk, 2026-09-29). */
+export function withSentForm(order: Order, posOrder: PosOrder): SentOrder {
+  const customer: SentOrder['customer'] = order.customer && { ...order.customer };
+  if (customer && posOrder.customer?.email === undefined) delete customer.email;
+  if (customer && posOrder.customer?.id === undefined) delete customer.id;
+  return { ...order, customer,
+    lineItems: order.lineItems.map((line, i) => ({ ...line, name: posOrder.lines[i].name })),
+    display: posOrder.display ? { ...order.display,
+      lines: order.display.lines.map((line, i) => ({ ...line,
+        discounts: line.discounts.map((discount, j) => ({ ...discount, label: posOrder.display!.lines[i].discounts[j].label })),
+      })),
+    } : order.display,
+  };
+}
+
+/** Bounds apply when the sent form is frozen; the outbox freezes older tills' stored orders before their first send. */
+export function freezeSentForm(order: PosOrder): PosOrder {
+  let changed = false;
+  const lines = order.lines.map((line) => {
+    const name = cutText(line.name, PAYLOAD_STRING_MAX);
+    changed ||= name !== line.name;
+    return { ...line, name };
+  });
+  const display = order.display && { ...order.display, lines: order.display.lines.map((line) => ({ ...line,
+    discounts: line.discounts.map((discount) => {
+      if (discount.label === undefined) return discount;
+      const label = cutText(discount.label, PAYLOAD_STRING_MAX);
+      changed ||= label !== discount.label;
+      return { ...discount, label };
+    }),
+  })) };
+  const payments = order.payments.map((payment) => {
+    if (payment.reference === undefined) return payment;
+    const reference = cutText(payment.reference, PAYLOAD_STRING_MAX);
+    changed ||= reference !== payment.reference;
+    return { ...payment, reference };
+  });
+  const customer = order.customer && { ...order.customer };
+  const localWarnings = [...(order.localWarnings ?? [])];
+  for (const [field, max] of [['email', 254], ['id', 64]] as const) {
+    if (customer && field in customer && !sendable(customer[field], max)) {
+      delete customer[field]; changed = true;
+      if (!localWarnings.some((warning) => warning.code === 'customer_omitted' && warning.field === field)) localWarnings.push({ code: 'customer_omitted', field });
+    }
+  }
+  return changed ? { ...order, lines, payments, customer, ...(display ? { display } : {}), ...(localWarnings.length ? { localWarnings } : {}) } : order;
+}
+
+/**
+ * Why a reference the till passes through without minting would fail order.create's shape check
+ * (over PAYLOAD_STRING_MAX, or a NUL), or null; `label` names it for the cashier. `useSale` also
+ * checks its options and an entered payment reference with it.
+ */
+export function referenceError(label: string, value: string | undefined): string | null {
+  const reason = referenceReason(value);
+  return reason === 'long' ? `${label} is too long (max ${PAYLOAD_STRING_MAX} characters)`
+    : reason === 'nul' ? `${label} contains a NUL character` : null;
+}
+
+/** referenceError's rule as a reason: 'long' (over PAYLOAD_STRING_MAX), 'nul', or null when finalize accepts the value. */
+export function referenceReason(value: string | undefined): 'long' | 'nul' | null {
+  if (value === undefined) return null;
+  if (value.length > PAYLOAD_STRING_MAX) return 'long';
+  return value.includes('\u0000') ? 'nul' : null;
+}
+
+/**
+ * Turns a fully paid builder Order into a pending PosOrder without mutating it. The PosOrder holds the sent form,
+ * frozen: line names and v3 discount labels are cut to PAYLOAD_STRING_MAX with NUL stripped (`cutText`), and a
+ * customer email or id the shape check would refuse is left out, so `toOrderCreateEnvelope` sends it unchanged.
+ */
+export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosOrder {
+  if (!order.lineItems.length) throw new Error('finalize: no lines');
+  // Defence in depth: the builder already clamps every discount to >= 0, so this should never fire.
+  if (order.discountMinor < 0
+    || order.lineItems.some((line) => line.discountMinor < 0)
+    || order.discounts.some((d) => d.amountMinor < 0)) {
+    throw new Error('finalize: negative discount');
+  }
+  // An old plugin would reject or mis-apply a version-2 payload; this guard rejects a discount only when the store can't take it yet (ADR-062).
+  // Checked as "any non-zero" rather than "> 0": defence in depth, since the builder already clamps every
+  // discount to >= 0, so a negative amountMinor should never reach here.
+  const hasDiscount = order.discountMinor !== 0
+    || order.lineItems.some((line) => line.discountMinor !== 0)
+    || order.discounts.some((d) => d.amountMinor !== 0);
+  if (hasDiscount && (options.capabilities?.orderCreate ?? 1) < 2) {
+    throw new Error('finalize: discounts are not supported by the server yet (order.create v2)');
+  }
+  for (const payment of order.payments) {
+    if (payment.method !== 'cash' && payment.method !== 'external') {
+      throw new Error(`finalize: unsupported payment method ${payment.method}`);
+    }
+  }
+  if (order.paidMinor < order.totalMinor) throw new Error('finalize: underpaid');
+  let change = order.paidMinor - order.totalMinor;
+  const cash = order.payments.reduce((sum, p) => sum + (p.method === 'cash' ? p.amountMinor : 0), 0);
+  if (change > cash) throw new Error('finalize: change exceeds cash');
+  // Refused before any id is minted, so such a value never reaches the stored order or the outbox.
+  // v3 also sends each line discount's id and each tax code (as taxByRate's codes); an id is never clamped.
+  const v3 = (options.capabilities?.orderCreate ?? 1) >= 3;
+  const references: Array<[string, string | undefined]> = [['registerId', options.registerId], ['cashierRef', options.cashierRef],
+    ...order.lineItems.flatMap((line, i): Array<[string, string | undefined]> => {
+      const name = `"${cutText(line.name, MESSAGE_NAME_MAX)}"`;
+      return [line.variantId !== undefined ? [`${name}: the variant id`, line.variantId] : [`${name}: the product id`, line.productId],
+        ...(v3 ? order.display.lines[i]?.discounts ?? [] : []).map((d): [string, string] => [`${name}: the discount id`, d.discountId]),
+        ...(v3 ? line.taxLines : []).map((tax): [string, string | undefined] => [`${name}: the tax code`, tax.code])];
+    }),
+    ...order.payments.map((payment): [string, string | undefined] => [`the ${payment.method} payment's reference`, payment.reference])];
+  for (const [field, value] of references) {
+    const message = referenceError(field, value);
+    if (message) throw new Error(`finalize: ${message}`);
+  }
+  const newId = options.newId ?? uuidv7;
+  const id = newId();
+  const lines = order.lineItems.map((line) => ({
+    id: newId(), productId: line.productId,
+    ...(line.variantId !== undefined ? { variantId: line.variantId } : {}),
+    name: line.name, sku: line.sku, quantity: line.quantity, unitPriceMinor: line.unitPriceMinor,
+    discountMinor: line.discountMinor, netMinor: line.netMinor,
+    taxLines: line.taxLines.map((tax) => ({ ...tax })),
+    ...(line.priceTaxModeConverted ? { taxInclusive: line.taxInclusive } : {}),
+  }));
+  const payments: PosOrderPayment[] = order.payments.map((payment) => ({
+    id: newId(), method: payment.method as PosOrderPayment['method'], amountMinor: payment.amountMinor,
+    ...(payment.reference !== undefined ? { reference: payment.reference } : {}),
+  }));
+  // A warning naming a payment the order no longer has is dropped and logged, never thrown: this runs at sale completion.
+  const localWarnings = options.localWarnings?.flatMap((warning): PosOrderLocalWarning[] => {
+    if (warning.code !== 'payment_reference_dropped') return [{ ...warning }];
+    const index = order.payments.findIndex((payment) => payment.id === warning.paymentId);
+    if (index === -1) {
+      try {
+        outboxLogger.warn('finalize: dropped a localWarnings entry naming an unknown payment', { orderId: id, paymentId: warning.paymentId });
+      } catch { /* a failing sink must never fail the sale */ }
+      return [];
+    }
+    return [{ ...warning, paymentId: payments[index].id }];
+  });
+  for (let i = payments.length - 1; i >= 0; i--) {
+    const payment = payments[i];
+    if (payment.method !== 'cash') continue;
+    payment.tenderedMinor = payment.amountMinor;
+    payment.changeMinor = Math.min(change, payment.tenderedMinor);
+    payment.amountMinor -= payment.changeMinor;
+    change -= payment.changeMinor;
+  }
+  if (payments.reduce((sum, p) => sum + p.amountMinor, 0) !== order.totalMinor) {
+    throw new Error('finalize: payments do not reconcile');
+  }
+  let display: PosOrder['display'];
+  let taxByRate: PosOrder['taxByRate'];
+  if ((options.capabilities?.orderCreate ?? 1) >= 3) {
+    if (order.display.lines.length !== order.lineItems.length
+      || order.display.lines.some((line, i) => line.lineId !== order.lineItems[i].id)) {
+      throw new Error('finalize: display lines do not match the order lines');
+    }
+    display = { currency: order.currency, exponent: minorUnitDigits(order.currency), ...order.display,
+      lines: order.display.lines.map((line, i) => ({
+        lineId: lines[i].id, amountMinor: line.amountMinor,
+        discounts: line.discounts.map(({ discountId, label, amountMinor }) => ({
+          discountId, ...(label !== undefined ? { label } : {}), amountMinor,
+        })),
+      })),
+    };
+    taxByRate = taxLinesByRate(order.lineItems, order.taxMinor, undefined, order.taxRounding).map(({ ratePpm, code, netMinor, amountMinor }) => ({
+      ratePpm, ...(code !== undefined ? { code } : {}), netMinor, amountMinor, grossMinor: netMinor + amountMinor,
+    }));
+    if (display.totalMinor !== order.totalMinor || display.taxMinor !== order.taxMinor
+      || display.taxInclusive !== order.pricesIncludeTax) {
+      throw new Error('finalize: display does not match the order');
+    }
+    if (taxByRate.reduce((sum, rate) => sum + rate.amountMinor, 0) !== order.taxMinor) {
+      throw new Error('finalize: tax by rate does not sum to the order tax');
+    }
+  }
+  // Frozen with the figures (#287), the default included, and never recomputed from the store's later capability:
+  // absent on the snapshot is the default the figures used; `custom` computes as the default but records itself.
+  const rounding = order.taxRounding ?? DEFAULT_TAX_ROUNDING;
+  const taxRounding: TaxRounding = rounding.granularity === 'custom' ? { granularity: 'custom' }
+    : { granularity: rounding.granularity, mode: rounding.mode };
+  const now = (options.now ?? new Date()).toISOString();
+  return freezeSentForm({
+    id, createdAt: now, updatedAt: now, commandId: newId(), syncStatus: 'pending',
+    currency: order.currency, pricesIncludeTax: order.pricesIncludeTax, lines, payments,
+    subtotalMinor: order.subtotalMinor, discountMinor: order.discountMinor,
+    taxMinor: order.taxMinor, totalMinor: order.totalMinor, taxRounding,
+    ...(display && taxByRate ? { display, taxByRate } : {}),
+    customer: order.customer ? { id: order.customer.id, name: order.customer.name,
+      ...(order.customer.email !== undefined ? { email: order.customer.email } : {}) } : null,
+    ...(order.note ? { note: order.note } : {}),
+    ...(options.registerId !== undefined ? { registerId: options.registerId } : {}),
+    ...(options.cashierRef !== undefined ? { cashierRef: options.cashierRef } : {}),
+    ...(localWarnings?.length ? { localWarnings } : {}),
+  });
+}

package/src/pos-order/index.ts

@@ -0,0 +1,10 @@
+export type { PosOrderSyncStatus, PosOrderLine, PosOrderPayment, PosOrderLocalWarning, PosOrderServerFailures, PosOrder } from './types';
+export { uuidv7 } from './uuidv7';
+export { finalizeOrder } from './finalize';
+export type { FinalizeOptions } from './finalize';
+export { toOrderCreateEnvelope, UnsupportedOrderVersionError } from './command';
+export { posOrderSchema, posOrderCollection } from './schema';
+export { addPosOrderCollection, PosOrderOpenClosedError, posOrdersLogger } from './open';
+export { getDeviceId } from './device-id';
+export { needsAttention } from './needs-attention';
+export { sameSale, OrderContentMismatchError } from './same-sale';

package/src/pos-order/needs-attention.ts

@@ -0,0 +1,16 @@
+import { knownWarnings } from '@tallyui/core';
+import type { PosOrder } from './types';
+
+/**
+ * The orders a cashier must look at: rejected, applied with a known warning, taken after their
+ * session closed (`lateSessionId`) or with local warnings (whatever the sync status), or pending with a `commandId` in
+ * `stuckCommandIds` (the outbox's `OutboxState.stuck`: the store keeps failing it), newest first.
+ * A warning code this till version doesn't know is not shown here (`knownWarnings`). Never changes `orders`.
+ */
+export function needsAttention(orders: PosOrder[], options: { stuckCommandIds?: readonly string[] } = {}): PosOrder[] {
+  return orders.filter((order) => order.syncStatus === 'rejected'
+    || (order.localWarnings?.length ?? 0) > 0
+    || (order.syncStatus === 'applied' && knownWarnings(order.warnings).length > 0) || order.lateSessionId !== undefined
+    || (order.syncStatus === 'pending' && options.stuckCommandIds?.includes(order.commandId) === true))
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}