@tallyui/pos 0.1.0 → 2.0.0

package/src/pos-order/schema.ts

@@ -0,0 +1,100 @@
+import { addRxPlugin, type MigrationStrategies, type RxJsonSchema } from 'rxdb';
+import { RxDBMigrationSchemaPlugin } from 'rxdb/plugins/migration-schema';
+import type { PosOrder } from './types';
+
+/**
+ * Version 1 adds the optional `sessionId` (ADR-032); nothing else changed from version 0.
+ * Version 2 adds three optional fields and changes nothing else: `lateSessionId` (ADR-032, late
+ * sale), and ADR-065's `display` and `taxByRate`, declared ahead of the job that writes them so a
+ * till migrates once. Create the collection with `posOrderCollection()`, never with this schema
+ * alone: RxDB refuses a version above 0 without its migration strategies.
+ */
+export const posOrderSchema: RxJsonSchema<PosOrder> = {
+  version: 2, primaryKey: 'id', type: 'object', additionalProperties: false,
+  properties: {
+    id: { type: 'string', maxLength: 36 },
+    commandId: { type: 'string', maxLength: 36 },
+    createdAt: { type: 'string', maxLength: 40 },
+    updatedAt: { type: 'string' },
+    currency: { type: 'string' },
+    pricesIncludeTax: { type: 'boolean' },
+    subtotalMinor: { type: 'integer' }, discountMinor: { type: 'integer' },
+    taxMinor: { type: 'integer' }, totalMinor: { type: 'integer' },
+    syncStatus: { type: 'string', enum: ['pending', 'applied', 'rejected'], maxLength: 10 },
+    note: { type: 'string' }, registerId: { type: 'string' }, sessionId: { type: 'string' }, cashierRef: { type: 'string' },
+    lines: { type: 'array', items: {
+      type: 'object', properties: {
+        id: { type: 'string', maxLength: 36 }, productId: { type: 'string' }, variantId: { type: 'string' },
+        name: { type: 'string' }, sku: { type: 'string' }, quantity: { type: 'integer' },
+        unitPriceMinor: { type: 'integer' }, discountMinor: { type: 'integer' }, netMinor: { type: 'integer' },
+        taxLines: { type: 'array', items: {
+          type: 'object', properties: { code: { type: 'string' }, ratePpm: { type: 'integer' }, taxMicros: { type: 'string' } },
+          required: ['ratePpm', 'taxMicros'],
+        } },
+      },
+      required: ['id', 'productId', 'name', 'sku', 'quantity', 'unitPriceMinor', 'discountMinor', 'netMinor', 'taxLines'],
+    } },
+    payments: { type: 'array', items: {
+      type: 'object', properties: {
+        id: { type: 'string', maxLength: 36 }, method: { type: 'string', enum: ['cash', 'external'] },
+        amountMinor: { type: 'integer' }, tenderedMinor: { type: 'integer' }, changeMinor: { type: 'integer' }, reference: { type: 'string' },
+      }, required: ['id', 'method', 'amountMinor'],
+    } },
+    customer: { type: ['object', 'null'], properties: { id: { type: 'string' }, name: { type: 'string' }, email: { type: 'string' } } },
+    serverRefs: { type: 'object', properties: {
+      orderId: { type: 'string' }, displayId: { type: 'string' }, totalMinor: { type: 'integer' },
+    }, required: ['orderId', 'totalMinor'] },
+    warnings: { type: 'array', items: {
+      type: 'object', properties: { code: { type: 'string', maxLength: 64 } },
+      required: ['code'], additionalProperties: true,
+    } },
+    error: { type: 'object', properties: { code: { type: 'string' }, message: { type: 'string' } }, required: ['code', 'message'] },
+    lateSessionId: { type: 'string' },
+    // The nested objects are closed too: loosening a schema later is free, tightening one costs a migration.
+    display: { type: 'object', additionalProperties: false, properties: {
+      currency: { type: 'string' }, exponent: { type: 'integer' }, taxInclusive: { type: 'boolean' },
+      subtotalMinor: { type: 'integer' }, discountMinor: { type: 'integer' }, taxMinor: { type: 'integer' },
+      totalMinor: { type: 'integer' }, orderDiscountMinor: { type: 'integer' },
+      lines: { type: 'array', items: {
+        type: 'object', additionalProperties: false, properties: {
+          lineId: { type: 'string' }, amountMinor: { type: 'integer' },
+          discounts: { type: 'array', items: {
+            type: 'object', additionalProperties: false,
+            properties: { discountId: { type: 'string' }, label: { type: 'string' }, amountMinor: { type: 'integer' } },
+            required: ['discountId', 'amountMinor'],
+          } },
+        }, required: ['lineId', 'amountMinor', 'discounts'],
+      } },
+    }, required: ['currency', 'exponent', 'taxInclusive', 'subtotalMinor', 'discountMinor', 'taxMinor', 'totalMinor', 'orderDiscountMinor', 'lines'] },
+    taxByRate: { type: 'array', items: {
+      type: 'object', additionalProperties: false, properties: {
+        ratePpm: { type: 'integer' }, code: { type: 'string' }, label: { type: 'string' }, netMinor: { type: 'integer' },
+        amountMinor: { type: 'integer' }, grossMinor: { type: 'integer' },
+      }, required: ['ratePpm', 'netMinor', 'amountMinor', 'grossMinor'],
+    } },
+  },
+  required: ['id', 'createdAt', 'currency', 'pricesIncludeTax', 'lines', 'subtotalMinor', 'discountMinor', 'taxMinor',
+    'totalMinor', 'payments', 'customer', 'syncStatus', 'commandId', 'updatedAt'],
+  indexes: ['createdAt', 'syncStatus', ['syncStatus', 'createdAt']],
+};
+
+/**
+ * The `pos_orders` collection config, with its migration strategies. Open the collection with
+ * `addPosOrderCollection(db)`, which uses this and settles the migration safely; adding this config
+ * directly leaves RxDB's own open path. `pos_orders` holds sales not yet sent, so no step may drop a
+ * document: versions 1 and 2 only add optional fields, so every order from version 0 or 1 passes
+ * unchanged.
+ *
+ * Within one run, RxDB 16.21 keeps an order that fails the new schema's validation: with a
+ * validating storage the migration stops with DM4 and the order stays in the older version's
+ * storage; without one it is copied as is. **Across runs, RxDB's own open path can lose it**: a
+ * failed run can leave its checkpoint past that order, and the next run then removes the older
+ * version's storage without copying it. `addPosOrderCollection` resets that checkpoint, so use it
+ * (`migration.test.ts`).
+ */
+export function posOrderCollection(): { schema: RxJsonSchema<PosOrder>; migrationStrategies: MigrationStrategies } {
+  // addRxPlugin ignores a plugin it already has.
+  addRxPlugin(RxDBMigrationSchemaPlugin);
+  const identity = (doc: PosOrder) => doc;
+  return { schema: posOrderSchema, migrationStrategies: { 1: identity, 2: identity } };
+}

package/src/pos-order/types.ts

@@ -0,0 +1,67 @@
+import type { CommandError, CommandServerRefs, CommandWarning, PaymentMethodKind } from '@tallyui/core';
+import type { DisplayTotals } from '../order/types';
+
+export type PosOrderSyncStatus = 'pending' | 'applied' | 'rejected';
+
+export interface PosOrderLine {
+  id: string;
+  productId: string;
+  variantId?: string;
+  name: string;
+  sku: string;
+  quantity: number;
+  unitPriceMinor: number;
+  /** Line discounts plus the allocated order-discount share, in the line's own tax mode (ADR-062). */
+  discountMinor: number;
+  netMinor: number;
+  taxLines: Array<{ code?: string; ratePpm: number; taxMicros: string }>;
+  /** This line's own tax mode; set only when it was converted from the store's (ADR-038 amendment). */
+  taxInclusive?: boolean;
+}
+
+export interface PosOrderPayment {
+  id: string;
+  method: PaymentMethodKind;
+  amountMinor: number;
+  tenderedMinor?: number;
+  changeMinor?: number;
+  reference?: string;
+}
+
+export interface PosOrder {
+  id: string;
+  createdAt: string;
+  currency: string;
+  pricesIncludeTax: boolean;
+  lines: PosOrderLine[];
+  subtotalMinor: number;
+  discountMinor: number;
+  taxMinor: number;
+  totalMinor: number;
+  payments: PosOrderPayment[];
+  customer: { id?: string; name?: string; email?: string } | null;
+  note?: string;
+  registerId?: string;
+  /**
+   * The register session the sale was taken in (ADR-032): its closure counts this order.
+   * Local only: `toOrderCreateEnvelope` never sends it.
+   */
+  sessionId?: string;
+  /**
+   * Set only by `useSale`'s late-sale path (ADR-032): the session the sale was taken for, which
+   * refused the stamp after the money was taken. Such an order has no `sessionId`, so no closure
+   * counts it. Local only: `toOrderCreateEnvelope` never sends it.
+   */
+  lateSessionId?: string;
+  /** ADR-065: the receipt's display figures, in integer minor units of `currency` at `exponent`. Not written yet. */
+  display?: DisplayTotals & { currency: string; exponent: number };
+  /** ADR-065: tax by rate, named as `taxLinesByRate` names them (`amountMinor` is the tax). Not written yet. */
+  taxByRate?: Array<{ ratePpm: number; code?: string; label?: string; netMinor: number; amountMinor: number; grossMinor: number }>;
+  cashierRef?: string;
+  syncStatus: PosOrderSyncStatus;
+  commandId: string;
+  serverRefs?: CommandServerRefs;
+  warnings?: CommandWarning[];
+  error?: CommandError;
+  updatedAt: string;
+}

package/src/pos-order/uuidv7.ts

@@ -0,0 +1,54 @@
+function format(ms: number, bytes: Uint8Array): string {
+  let timestamp = BigInt(ms);
+  for (let i = 5; i >= 0; i--) {
+    bytes[i] = Number(timestamp & 0xffn);
+    timestamp >>= 8n;
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x70;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+export function createUuidv7(options?: {
+  now?: () => number;
+  randomBytes?: (n: number) => Uint8Array;
+}): () => string {
+  let lastMs = -Infinity;
+  let lastRand = 0n;
+  return () => {
+    const randomBytes = options?.randomBytes;
+    if (!randomBytes && !globalThis.crypto?.getRandomValues) throw new Error('uuidv7: no random source');
+    let ms = Math.max((options?.now ?? Date.now)(), lastMs);
+    let rand = lastRand + 1n;
+    if (ms === lastMs && rand === 2n ** 74n) ms = lastMs + 1;
+    if (ms !== lastMs) {
+      const bytes = randomBytes ? randomBytes(16) : globalThis.crypto.getRandomValues(new Uint8Array(16));
+      rand = (BigInt(bytes[6] & 0x0f) << 8n) | BigInt(bytes[7]);
+      rand = (rand << 6n) | BigInt(bytes[8] & 0x3f);
+      for (let i = 9; i < 16; i++) rand = (rand << 8n) | BigInt(bytes[i]);
+    }
+    lastMs = ms;
+    lastRand = rand;
+    const bytes = new Uint8Array(16);
+    for (let i = 15; i >= 9; i--) {
+      bytes[i] = Number(rand & 0xffn);
+      rand >>= 8n;
+    }
+    bytes[8] = Number(rand & 0x3fn);
+    rand >>= 6n;
+    bytes[7] = Number(rand & 0xffn);
+    bytes[6] = Number(rand >> 8n);
+    return format(ms, bytes);
+  };
+}
+
+const monotonic = createUuidv7();
+
+/** RFC 9562 UUIDv7: monotonic with no arguments; stateless with an explicit timestamp or random source. */
+export function uuidv7(now?: number, randomBytes?: (n: number) => Uint8Array): string {
+  if (now === undefined && randomBytes === undefined) return monotonic();
+  const ms = now ?? Date.now();
+  if (!randomBytes && !globalThis.crypto?.getRandomValues) throw new Error('uuidv7: no random source');
+  return format(ms, randomBytes ? randomBytes(16) : globalThis.crypto.getRandomValues(new Uint8Array(16)));
+}

package/src/product/index.ts

@@ -0,0 +1,2 @@
+export { searchProducts } from './search-products';
+export { withStockOverlay, getProductStock, stockOverlay$, stockOverlayAsOf$ } from './stock';

package/src/product/search-products.ts

@@ -0,0 +1,29 @@
+import type { ProductTraits } from '@tallyui/core';
+
+/**
+ * Filters product documents by a cashier's search term, through traits, so
+ * it works the same on every backend.
+ *
+ * Every word of the term must appear in the product name, SKU or barcode
+ * (case-insensitive, any order). A term that exactly equals a barcode or SKU
+ * returns just those products, so a scanner hit is never buried among name
+ * matches. An empty term returns the input unchanged.
+ */
+export function searchProducts<Doc>(docs: Doc[], term: string, traits: ProductTraits<Doc>): Doc[] {
+  const query = term.trim().toLowerCase();
+  if (!query) return docs;
+
+  const codes = (doc: Doc) =>
+    [traits.getSku(doc), traits.getBarcode(doc)]
+      .filter((code): code is string => Boolean(code))
+      .map((code) => code.toLowerCase());
+
+  const exact = docs.filter((doc) => codes(doc).includes(query));
+  if (exact.length) return exact;
+
+  const words = query.split(/\s+/);
+  return docs.filter((doc) => {
+    const haystack = [traits.getName(doc).toLowerCase(), ...codes(doc)].join(' ');
+    return words.every((word) => haystack.includes(word));
+  });
+}

package/src/product/stock.ts

@@ -0,0 +1,25 @@
+import type { RxCollection } from 'rxdb';
+import { map, type Observable } from 'rxjs';
+
+import { STOCK_LEVELS_LAST_PASS } from '@tallyui/core';
+
+// The pure helpers live in core so components can use them without RxDB.
+export { withStockOverlay, getProductStock } from '@tallyui/core';
+
+/** The `stock_levels` collection as a live map of key to stock value. */
+export function stockOverlay$(collection: RxCollection): Observable<Map<string, unknown>> {
+  return collection.find().$.pipe(
+    map((rows) => new Map(rows.map((row) => [row.primary, row.get('value')] as [string, unknown]))),
+  );
+}
+
+/**
+ * When the overlay was last confirmed by a successful pass (ISO 8601), or
+ * undefined before any pass. Read from the collection's local document, so a
+ * tab or screen that does not hold the runner can show it too.
+ */
+export function stockOverlayAsOf$(collection: RxCollection): Observable<string | undefined> {
+  return collection.getLocal$<{ completedAt: string }>(STOCK_LEVELS_LAST_PASS).pipe(
+    map((doc) => doc?.get('completedAt') as string | undefined),
+  );
+}

package/src/receipt/build-receipt-data.ts

@@ -1,18 +1,26 @@
-import type { Order } from '../order/types';
+import type { Discount, Order } from '../order/types';
+import { roundMicrosToMinor, taxLinesByRate } from '../tax/exact';
 import type { ReceiptConfig, ReceiptData } from './types';
 
 export function buildReceiptData(order: Order, config: ReceiptConfig): ReceiptData {
-  const taxByRate = new Map<number, number>();
-  for (const line of order.lineItems) {
-    const existing = taxByRate.get(line.taxRate) ?? 0;
-    taxByRate.set(line.taxRate, existing + line.taxAmount);
-  }
+  // Drops the shared helper's `netMinor` (the Z report's own use): the receipt's tax summary
+  // never showed it, and an exact-shape test elsewhere in this package pins that.
+  const taxLines = taxLinesByRate(order.lineItems, order.taxMinor, config.taxLabels).map(
+    ({ label, code, ratePpm, amountMinor }) => ({ label, code, ratePpm, amountMinor }),
+  );
 
-  const taxLines = Array.from(taxByRate.entries()).map(([rate, amount]) => ({
-    label: config.taxLabels?.[rate] ?? `Tax ${Math.round(rate * 100)}%`,
-    rate,
-    amount: Math.round(amount * 100) / 100,
-  }));
+  // Every receipt line is shown in the order's mode. A line whose price had the other mode is
+  // converted by its tax share as the order total rounds it: the rounded running tax sum,
+  // started from the exclusive lines the order already rounds, so the shares add up exactly.
+  let taxSoFar = order.lineItems.reduce(
+    (sum, li) => li.taxInclusive || li.priceTaxModeConverted ? sum : sum + BigInt(li.taxMicros), 0n);
+  const lineTotals = order.lineItems.map((li) => {
+    if (!li.priceTaxModeConverted) return li.netMinor;
+    const share = roundMicrosToMinor(taxSoFar + BigInt(li.taxMicros)) - roundMicrosToMinor(taxSoFar);
+    taxSoFar += BigInt(li.taxMicros);
+    return li.taxInclusive ? li.netMinor - share : li.netMinor + share;
+  });
+  const label = (d: Discount) => d.label ?? d.couponCode ?? `${d.type} discount`;
 
   return {
     header: {
@@ -23,30 +31,36 @@ export function buildReceiptData(order: Order, config: ReceiptConfig): ReceiptDa
       cashier: config.cashier,
       register: config.register,
     },
-    lineItems: order.lineItems.map((li) => ({
+    lineItems: order.lineItems.map((li, index) => ({
       name: li.name,
       sku: li.sku,
       quantity: li.quantity,
-      unitPrice: li.price,
-      lineTotal: li.lineTotal,
+      unitPriceMinor: li.unitPriceMinor,
+      lineTotalMinor: lineTotals[index],
+      // Line plus allocated order discounts, in the line's own mode; lineTotalMinor is already after it (ADR-062).
+      ...(li.discountMinor > 0 ? { discountMinor: li.discountMinor } : {}),
+      displayAmountMinor: order.display.lines[index].amountMinor,
+      displayDiscounts: order.display.lines[index].discounts.map((row, i) => ({ label: label(li.discounts[i]), amountMinor: row.amountMinor })),
     })),
     discounts: order.discounts.map((d) => ({
-      label: d.label ?? d.couponCode ?? `${d.type} discount`,
-      amount: d.amount,
+      label: label(d),
+      amountMinor: d.amountMinor,
     })),
+    orderDiscountMinor: order.display.orderDiscountMinor,
     totals: {
-      subtotal: order.subtotal,
-      discountTotal: order.discountTotal,
+      taxInclusive: order.display.taxInclusive,
+      subtotalMinor: order.display.subtotalMinor,
+      discountMinor: order.display.discountMinor,
       taxLines,
-      taxTotal: order.taxTotal,
-      total: order.total,
+      taxMinor: order.display.taxMinor,
+      totalMinor: order.display.totalMinor,
     },
     payments: order.payments.map((p) => ({
       method: p.method,
-      amount: p.amount,
+      amountMinor: p.amountMinor,
       reference: p.reference,
     })),
-    changeDue: order.changeDue,
+    changeDueMinor: order.changeDueMinor,
     footer: {
       note: order.note || undefined,
       barcode: order.id,

package/src/receipt/types.ts

@@ -2,8 +2,12 @@ export interface ReceiptLineItem {
   name: string;
   sku: string;
   quantity: number;
-  unitPrice: number;
-  lineTotal: number;
+  unitPriceMinor: number;
+  /** After every discount, including the line's order share, in the order's mode. Not the figure to print above the subtotal: use displayAmountMinor. */
+  lineTotalMinor: number;
+  discountMinor?: number;     // this line's discounts, already taken off lineTotalMinor; absent when 0
+  displayAmountMinor: number; // before any discount, in the display mode; Σ = totals.subtotalMinor (ADR-063)
+  displayDiscounts: { label: string; amountMinor: number }[]; // this line's own discounts, in the display mode
 }
 
 export interface ReceiptData {
@@ -16,16 +20,18 @@ export interface ReceiptData {
     register?: string;
   };
   lineItems: ReceiptLineItem[];
-  discounts: { label: string; amount: number }[];
+  discounts: { label: string; amountMinor: number }[];
+  orderDiscountMinor: number;   // the order discounts as one row, in the display mode; + Σ displayDiscounts = totals.discountMinor
   totals: {
-    subtotal: number;
-    discountTotal: number;
-    taxLines: { label: string; rate: number; amount: number }[];
-    taxTotal: number;
-    total: number;
+    taxInclusive: boolean;      // from order.display: tax is added (false) or included (true)
+    subtotalMinor: number;      // order.display.subtotalMinor: before discounts, in the display mode
+    discountMinor: number;      // order.display.discountMinor: every discount, in the display mode (>= 0)
+    taxLines: { label: string; code?: string; ratePpm: number; amountMinor: number }[];
+    taxMinor: number;           // order.display.taxMinor
+    totalMinor: number;         // order.display.totalMinor
   };
-  payments: { method: string; amount: number; reference?: string }[];
-  changeDue: number;
+  payments: { method: string; amountMinor: number; reference?: string }[];
+  changeDueMinor: number;
   footer: {
     note?: string;
     barcode?: string;

package/src/register/__fixtures__/closure-local-row.json

@@ -0,0 +1,61 @@
+{
+  "id": "closure-fixture",
+  "session_id": "session-fixture",
+  "register_id": "register-fixture",
+  "store_key": "1",
+  "business_day": "2026-09-11",
+  "closed_by": "1",
+  "corrections_count": 0,
+  "number": 42,
+  "opened_at": "2026-09-11T08:00:00Z",
+  "closed_at": "2026-09-11T17:00:00Z",
+  "till_expected": { "cash": 18000, "card": 12000 },
+  "expected": { "cash": 18000, "card": 12000 },
+  "counted": { "cash": 17800, "card": 12000 },
+  "variance": { "cash": -200, "card": 0 },
+  "period_sales_total_minor": 25000,
+  "period_refunds_total_minor": 5000,
+  "perpetual_sales_total_minor": 525000,
+  "perpetual_refunds_total_minor": 25000,
+  "unsynced_count": 2,
+  "unsynced_total_minor": 1200,
+  "software_version": "preview",
+  "breakdowns": {
+    "currency": "USD",
+    "transaction_count": 12,
+    "refund_count": 2,
+    "cashiers": [{ "id": "1", "name": "Alex" }],
+    "register_name": "Main register",
+    "opened_by": "1",
+    "approved_by": "1",
+    "opened_by_name": "Alex",
+    "closed_by_name": "Alex",
+    "approved_by_name": "Alex",
+    "payment_methods": {
+      "cash": { "sales_minor": 13000, "refunds_minor": 5000 },
+      "card": { "sales_minor": 12000, "refunds_minor": 0 }
+    },
+    "tax_rates": {
+      "vat": { "name": "VAT 20%", "net_minor": 16667, "tax_minor": 3333, "gross_minor": 20000 }
+    },
+    "opening_float": { "expected_minor": 10000, "counted_minor": 10000, "variance_minor": 0 },
+    "movements": [
+      {
+        "id": "movement-fixture",
+        "type": "paid_out",
+        "amountMinor": 500,
+        "reason": "Petty cash",
+        "created_at_gmt": "2026-09-11T10:00:00Z",
+        "created_by": "1",
+        "voids": null,
+        "voided_by": "sample-void"
+      }
+    ]
+  },
+  "order_ids": [],
+  "movement_ids": [],
+  "server_closure_id": null,
+  "printed_at": null,
+  "print_count": 0,
+  "number_retried": false
+}