@tallyui/pos 0.1.0 → 2.0.0

package/src/register/register-document.ts

@@ -0,0 +1,243 @@
+/**
+ * The till's identity and counters: one RxDB local document, `register`. Port provenance
+ * (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`.
+ *
+ * The host is whatever carries local documents: `register_sessions`, created with
+ * `registerSessionCollection` (a Tally database has no database-level local documents). WCPOS
+ * keys its buckets by site UUID plus a numeric WooCommerce store id; TallyUI keys them by one
+ * neutral `storeKey` the app derives (for example the connector id plus the base URL). WCPOS's
+ * module-level snapshots (`getRegisterSnapshot`, `getRegisterId`, `getCurrentBoundRegisterId`)
+ * are not ported: callers pass the host and read the document explicitly.
+ */
+import type { RxLocalDocumentMutation } from 'rxdb';
+import { map } from 'rxjs';
+import type { Closure } from './schemas';
+
+export type RegisterHost = RxLocalDocumentMutation<any>;
+
+export type RegisterCounters = {
+  last_closure_number: number;
+  perpetual_sales_total_minor: number;
+  perpetual_refunds_total_minor: number;
+  counters_started_at?: string | null;
+};
+
+/**
+ * One register's counters, plus the closure being written: the draft is reserved here, in the
+ * same atomic write as its number, and `applied` once its period is in the perpetual totals.
+ */
+export type RegisterBucket = Partial<RegisterCounters> & {
+  closure_reservation?: { row: Closure; applied: boolean };
+  /** Closure ids the orphan-stamp sweep has already checked (ADR-032, the #158 follow-ups): a
+   *  local-document field, so bounding the sweep needs no schema bump. */
+  swept_closure_ids?: string[];
+};
+
+export interface RegisterStore {
+  sale_counter: number;
+  registers?: Record<string, RegisterBucket>;
+  /** The register (drawer) this till is bound to in this store. */
+  register_id?: string | null;
+  register_name?: string | null;
+}
+
+export interface RegisterDocument {
+  id: string;
+  name: string;
+  /** The caller's platform, for example `'ios'` or `'web'`. */
+  platform: string;
+  created_at: string;
+  /** Keyed by `storeKey`. */
+  stores: Record<string, RegisterStore>;
+}
+
+const REGISTER = 'register';
+
+export function mintUuid(): string {
+  const id = globalThis.crypto?.randomUUID?.();
+  if (id) return id;
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  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 async function readRegister(host: RegisterHost): Promise<RegisterDocument | null> {
+  return ((await host.getLocal<RegisterDocument>(REGISTER))?.toJSON(true).data as RegisterDocument | undefined) ?? null;
+}
+
+/** Reads the register document, minting it on first use; concurrent callers get the same one. */
+export async function ensureRegister(host: RegisterHost, platform: string): Promise<RegisterDocument> {
+  const existing = await readRegister(host);
+  if (existing) return existing;
+  const id = mintUuid().toLowerCase();
+  const data: RegisterDocument = {
+    id,
+    name: `Register ${id.slice(-4).toUpperCase()}`,
+    platform,
+    created_at: new Date().toISOString(),
+    stores: {},
+  };
+  try {
+    await host.insertLocal(REGISTER, data);
+    return data;
+  } catch (error) {
+    const winner = await readRegister(host);
+    if (winner) return winner;
+    throw error;
+  }
+}
+
+export function observeRegister$(host: RegisterHost) {
+  return host
+    .getLocal$<RegisterDocument>(REGISTER)
+    .pipe(map((doc) => (doc?.toJSON(true).data as RegisterDocument | undefined) ?? null));
+}
+
+/** Applies `modify` to one store's bucket in a single atomic write; `undefined` leaves the document unchanged. */
+async function modifyStore(
+  host: RegisterHost,
+  storeKey: string,
+  modify: (store: RegisterStore | undefined) => RegisterStore | undefined,
+) {
+  const doc = await host.getLocal<RegisterDocument>(REGISTER);
+  if (!doc) throw new Error('Register is not initialized');
+  // RxDB can batch modifiers and return the same final document to each caller, so callers
+  // capture their own result inside `modify`.
+  await doc.incrementalModify((data) => {
+    const store = modify(data.stores[storeKey]);
+    return store ? { ...data, stores: { ...data.stores, [storeKey]: store } } : data;
+  });
+}
+
+export function getBoundRegisterId(register: RegisterDocument | null, storeKey: string): string | null {
+  return register?.stores?.[storeKey]?.register_id ?? null;
+}
+
+export async function readBoundRegister(host: RegisterHost, storeKey: string) {
+  const register = await readRegister(host);
+  const id = getBoundRegisterId(register, storeKey);
+  return id ? { id, name: register?.stores[storeKey]?.register_name ?? '' } : null;
+}
+
+export function bindRegister(host: RegisterHost, storeKey: string, register: { id: string | null; name: string | null }) {
+  return modifyStore(host, storeKey, (store) => ({
+    ...(store ?? { sale_counter: 0 }),
+    register_id: register.id,
+    register_name: register.name,
+  }));
+}
+
+export function unbindRegister(host: RegisterHost, storeKey: string) {
+  return modifyStore(host, storeKey, (store) => store && { ...store, register_id: null, register_name: null });
+}
+
+export async function nextSaleCounter(host: RegisterHost, storeKey: string): Promise<number> {
+  let counter = 0;
+  await modifyStore(host, storeKey, (store) => {
+    counter = (store?.sale_counter ?? 0) + 1;
+    return { ...(store ?? {}), sale_counter: counter };
+  });
+  return counter;
+}
+
+function withRegister(store: RegisterStore | undefined, registerId: string, bucket: RegisterBucket): RegisterStore {
+  const base = store ?? { sale_counter: 0 };
+  return { ...base, registers: { ...base.registers, [registerId]: bucket } };
+}
+
+/**
+ * Mints the register's next closure number. Given the closure draft, it reserves the draft with
+ * its number and perpetual totals in the same atomic write, and a retry of the same draft gets the
+ * same number back. A different draft is refused while an earlier one is reserved but not yet
+ * applied (`closure_write_incomplete`).
+ */
+export async function mintClosureNumber(
+  host: RegisterHost,
+  storeKey: string,
+  registerId: string,
+  closure?: Closure,
+): Promise<number> {
+  let number = 0;
+  await modifyStore(host, storeKey, (store) => {
+    const register = store?.registers?.[registerId] ?? {};
+    const reservation = register.closure_reservation;
+    if (closure && reservation?.row.id === closure.id && !!reservation.row.number_retried === !!closure.number_retried) {
+      number = reservation.row.number;
+      return undefined;
+    }
+    if (closure && reservation && reservation.row.id !== closure.id && !reservation.applied) {
+      throw new Error('closure_write_incomplete');
+    }
+    number = (register.last_closure_number ?? 0) + 1;
+    // A re-mint of a closure whose period was already applied to the register must not
+    // add it again: the register totals already carry it.
+    const applied = closure && reservation?.row.id === closure.id && reservation.applied ? reservation.row : null;
+    const sales = closure
+      ? (register.perpetual_sales_total_minor ?? 0) - (applied?.period_sales_total_minor ?? 0) + closure.period_sales_total_minor
+      : 0;
+    const refunds = closure
+      ? (register.perpetual_refunds_total_minor ?? 0) - (applied?.period_refunds_total_minor ?? 0) + closure.period_refunds_total_minor
+      : 0;
+    const next = closure
+      ? {
+          row: { ...closure, number, perpetual_sales_total_minor: sales, perpetual_refunds_total_minor: refunds },
+          applied: !!applied || !!closure.number_retried,
+        }
+      : reservation;
+    return withRegister(store, registerId, {
+      ...register,
+      last_closure_number: number,
+      ...(next ? { closure_reservation: next } : {}),
+      // An applied period follows the closure row it came from.
+      ...(applied ? { perpetual_sales_total_minor: sales, perpetual_refunds_total_minor: refunds } : {}),
+    });
+  });
+  return number;
+}
+
+/**
+ * Adds a closed period to the register's perpetual totals. With `closureId`, it applies that
+ * reserved closure once: the totals become the reservation's, and a repeat does nothing.
+ */
+export function advancePerpetual(
+  host: RegisterHost,
+  storeKey: string,
+  registerId: string,
+  period: { salesMinor: number; refundsMinor: number; closureId?: string },
+) {
+  return modifyStore(host, storeKey, (store) => {
+    const register = store?.registers?.[registerId] ?? {};
+    const reservation = register.closure_reservation;
+    if (period.closureId && (!reservation || reservation.row.id !== period.closureId || reservation.applied)) {
+      return undefined;
+    }
+    const sales = register.perpetual_sales_total_minor ?? 0;
+    const refunds = register.perpetual_refunds_total_minor ?? 0;
+    return withRegister(store, registerId, {
+      ...register,
+      ...(period.closureId && reservation ? { closure_reservation: { ...reservation, applied: true } } : {}),
+      perpetual_sales_total_minor: period.closureId && reservation
+        ? Math.max(sales, reservation.row.perpetual_sales_total_minor)
+        : sales + period.salesMinor,
+      perpetual_refunds_total_minor: period.closureId && reservation
+        ? Math.max(refunds, reservation.row.perpetual_refunds_total_minor)
+        : refunds + period.refundsMinor,
+      counters_started_at: register.counters_started_at ?? new Date().toISOString(),
+    });
+  });
+}
+
+/**
+ * Adds closure ids to the register's swept set (ADR-032, the #158 follow-ups), once each: the
+ * orphan-stamp sweep's bound, so a closure already checked costs the sweep no `pos_orders` query.
+ */
+export function markClosuresSwept(host: RegisterHost, storeKey: string, registerId: string, closureIds: readonly string[]) {
+  return modifyStore(host, storeKey, (store) => {
+    const register = store?.registers?.[registerId] ?? {};
+    const swept = new Set(register.swept_closure_ids);
+    closureIds.forEach((closureId) => swept.add(closureId));
+    return withRegister(store, registerId, { ...register, swept_closure_ids: [...swept] });
+  });
+}

package/src/register/schemas.ts

@@ -0,0 +1,175 @@
+/**
+ * The register's local collections (ADR-032): sessions, cash movements and closures. Port
+ * provenance (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`, where they are at versions 1, 0
+ * and 1; each starts at version 0 here.
+ *
+ * All three are local only, like `pos_orders`: the app creates them and never replicates them
+ * (a replicated collection must never take local writes, #53). WCPOS's outbox fields
+ * (`sync_status`, attempts, next time, error) and closures' server and receipt fields are gone;
+ * sending sessions to a server is registers job c.
+ *
+ * Money is integer minor units: WCPOS's decimal strings become `*_minor` integers (`amountMinor`
+ * on a movement, matching `Movement`), and a tender map (`counted`, `expected`, `variance`, keyed
+ * by method) holds integers. People (`opened_by`, `created_by`, ...) are the backend's user id
+ * as a string, since not every backend's is a number.
+ */
+import { addRxPlugin, type JsonSchema, type RxJsonSchema } from 'rxdb';
+import { RxDBLocalDocumentsPlugin } from 'rxdb/plugins/local-documents';
+
+type TenderMap = Record<string, number>;
+
+export interface RegisterSession {
+  id: string;
+  register_id: string;
+  /** The app's neutral store key (see `bindRegister`). */
+  store_key?: string | null;
+  status: 'open' | 'counting' | 'closed';
+  /** The store's day the session opened, `yyyy-MM-dd`. */
+  business_day?: string;
+  opened_at_gmt: string;
+  opened_by?: string | null;
+  expected_float_minor?: number | null;
+  counted_float_minor: number;
+  opening_variance_minor?: number | null;
+  counting_started_at_gmt?: string | null;
+  closed_at_gmt?: string | null;
+  closed_by?: string | null;
+  approval_required?: boolean;
+  approved_by?: string | null;
+  counted?: TenderMap | null;
+  closure_id?: string | null;
+  /** The last local transition, kept for a server to acknowledge (job c). */
+  pending_status?: string | null;
+  server_status?: string | null;
+  status_at?: string | null;
+  approver_token?: string | null;
+  /** A server's expected figures; cleared before every money action (`requireOpenSession`). */
+  server_expected?: TenderMap | null;
+  server_sales_count?: number | null;
+}
+
+export interface CashMovement {
+  id: string;
+  session_id: string;
+  type: 'paid_in' | 'paid_out' | 'no_sale' | 'void';
+  amountMinor: number;
+  reason: string;
+  created_at_gmt: string;
+  created_by?: string | null;
+  /** On a `void` row: the movement it reverses. */
+  voids?: string | null;
+  /** On a reversed movement: its `void` row. */
+  voided_by?: string | null;
+}
+
+export interface Closure {
+  id: string;
+  session_id: string;
+  register_id: string;
+  store_key?: string | null;
+  business_day?: string;
+  closed_by?: string | null;
+  corrections_count?: number;
+  number: number;
+  opened_at: string;
+  closed_at: string;
+  till_expected: TenderMap;
+  expected: TenderMap;
+  counted: TenderMap;
+  variance: TenderMap;
+  period_sales_total_minor: number;
+  /** Always 0 until TallyUI has a refund model (ADR-032 amendment 1). */
+  period_refunds_total_minor: number;
+  perpetual_sales_total_minor: number;
+  perpetual_refunds_total_minor: number;
+  /** This session's orders still waiting for the outbox, and their payments' total. */
+  unsynced_count: number;
+  unsynced_total_minor: number;
+  software_version: string;
+  breakdowns: Record<string, unknown>;
+  order_ids: string[];
+  movement_ids: string[];
+  server_closure_id?: string | null;
+  printed_at?: string | null;
+  print_count: number;
+  number_retried?: boolean;
+}
+
+const id: JsonSchema = { type: 'string', maxLength: 36 };
+const text: JsonSchema = { type: 'string' };
+const nullableText: JsonSchema = { type: ['string', 'null'] };
+const minor: JsonSchema = { type: 'integer' };
+const nullableMinor: JsonSchema = { type: ['integer', 'null'] };
+const tenders: JsonSchema = { type: 'object', additionalProperties: minor };
+
+export const registerSessionSchema: RxJsonSchema<RegisterSession> = {
+  title: 'Register sessions', version: 0, primaryKey: 'id', type: 'object', additionalProperties: false,
+  properties: {
+    id, register_id: id, store_key: nullableText,
+    status: { type: 'string', enum: ['open', 'counting', 'closed'], maxLength: 8 },
+    business_day: { type: 'string', maxLength: 10 },
+    opened_at_gmt: text, opened_by: nullableText,
+    expected_float_minor: nullableMinor, counted_float_minor: minor, opening_variance_minor: nullableMinor,
+    counting_started_at_gmt: nullableText, closed_at_gmt: nullableText, closed_by: nullableText,
+    approval_required: { type: 'boolean', default: false }, approved_by: nullableText,
+    counted: { type: ['object', 'null'], additionalProperties: minor },
+    closure_id: nullableText,
+    pending_status: { ...nullableText, default: null },
+    server_status: { ...nullableText, default: null },
+    status_at: { ...nullableText, default: null },
+    approver_token: { ...nullableText, default: null },
+    server_expected: { type: ['object', 'null'], additionalProperties: minor, default: null },
+    server_sales_count: { type: ['integer', 'null'], default: null },
+  },
+  required: ['id', 'register_id', 'status', 'opened_at_gmt', 'counted_float_minor'],
+  indexes: [['register_id', 'status']],
+};
+
+/**
+ * Create `register_sessions` with this: the register document (`register-document.ts`) is a
+ * local document on this collection, since a Tally database has no database-level ones.
+ */
+export function registerSessionCollection() {
+  // addRxPlugin ignores a plugin it already has.
+  addRxPlugin(RxDBLocalDocumentsPlugin);
+  return { schema: registerSessionSchema, localDocuments: true } as const;
+}
+
+export const cashMovementSchema: RxJsonSchema<CashMovement> = {
+  title: 'Cash movements', version: 0, primaryKey: 'id', type: 'object', additionalProperties: false,
+  properties: {
+    id, session_id: id,
+    type: { type: 'string', enum: ['paid_in', 'paid_out', 'no_sale', 'void'] },
+    amountMinor: minor, reason: text, created_at_gmt: text, created_by: nullableText,
+    voids: nullableText, voided_by: nullableText,
+  },
+  required: ['id', 'session_id', 'type', 'amountMinor', 'reason', 'created_at_gmt'],
+  indexes: [['session_id']],
+};
+
+export const closureSchema: RxJsonSchema<Closure> = {
+  title: 'Register closures', version: 0, primaryKey: 'id', type: 'object', additionalProperties: false,
+  properties: {
+    id, session_id: id, register_id: id, store_key: nullableText,
+    business_day: { type: 'string', maxLength: 10 },
+    closed_by: nullableText, corrections_count: { type: 'integer' },
+    number: { type: 'integer' }, opened_at: text, closed_at: text,
+    till_expected: tenders, expected: tenders, counted: tenders, variance: tenders,
+    period_sales_total_minor: minor, period_refunds_total_minor: minor,
+    perpetual_sales_total_minor: minor, perpetual_refunds_total_minor: minor,
+    unsynced_count: { type: 'integer' }, unsynced_total_minor: minor,
+    software_version: text,
+    breakdowns: { type: 'object', additionalProperties: true },
+    order_ids: { type: 'array', items: text },
+    movement_ids: { type: 'array', items: text },
+    server_closure_id: { ...nullableText, default: null },
+    printed_at: { ...nullableText, default: null },
+    print_count: { type: 'integer', default: 0 },
+    number_retried: { type: 'boolean', default: false },
+  },
+  required: ['id', 'session_id', 'register_id', 'number', 'opened_at', 'closed_at', 'till_expected', 'expected',
+    'counted', 'variance', 'period_sales_total_minor', 'period_refunds_total_minor', 'perpetual_sales_total_minor',
+    'perpetual_refunds_total_minor', 'unsynced_count', 'unsynced_total_minor', 'software_version', 'breakdowns',
+    'order_ids', 'movement_ids', 'print_count'],
+  indexes: [['register_id'], ['session_id']],
+};