@teincfood/core 0.9.23 → 0.9.25

package/dist/db/migrations.js

@@ -423,4 +423,29 @@ export const MIGRATIONS = [
         `);
         },
     },
+    {
+        version: 12,
+        up: async (db) => {
+            // Payment timestamp at the top level of the order.
+            //
+            // The server returns `paid_at` on the order and (for cash sales taken at
+            // the till) no payment transaction at all. Keeping the timestamp only
+            // inside the `payment` JSON blob meant every pull overwrote a locally
+            // paid cash order with the server's `{is_paid:false, paid_at:null}`,
+            // so the row read back as UNPAID. One column, backfilled from the blob,
+            // is the single local source of truth.
+            await db.execAsync(`
+          ALTER TABLE orders ADD COLUMN paid_at TEXT;
+        `);
+            try {
+                await db.execAsync(`
+            UPDATE orders
+               SET paid_at = json_extract(payment, '$.paid_at')
+             WHERE paid_at IS NULL
+               AND json_extract(payment, '$.paid_at') IS NOT NULL;
+          `);
+            }
+            catch { }
+        },
+    },
 ];

package/dist/db/operations.d.ts

@@ -66,14 +66,52 @@ export interface OrderRow {
     inserted_at: string;
     updated_at: string | null;
     hlc: string | null;
+    paid_at?: string | null;
     deleted_at: string | null;
     sync_failed_at?: string | null;
     sync_error?: string | null;
 }
+/** True when the order has any recorded payment. */
+export declare function isOrderPaid(order: {
+    is_paid?: boolean;
+    paid_at?: string | null;
+    payment?: unknown;
+} | null | undefined): boolean;
 export declare function insertOrder(db: SQLiteDatabase, order: import("../types/api/seller.api").SellerOrder & {
     hlc?: string;
 }): Promise<void>;
 export declare function getOrderById(db: SQLiteDatabase, businessId: string, idOrNumber: string): Promise<import("../types/api/seller.api").SellerOrder | null>;
+/**
+ * Local intent for an order that still has unsynced work in `sync_jobs`.
+ *
+ * While a command is queued the device's intent must win over the server
+ * copy: a pull that lands before the command syncs would otherwise revert a
+ * queued accept (or a queued cash payment) back to the server's older state.
+ *
+ * `status` is the target status of the LAST queued transition, `isPaid` is
+ * true when a cash confirmation is still queued.
+ */
+export interface PendingOrderIntent {
+    status: string | null;
+    isPaid: boolean;
+    hasPending: boolean;
+}
+export declare function getPendingOrderIntent(db: SQLiteDatabase, businessId: string, orderId: string): Promise<PendingOrderIntent>;
+/**
+ * Write a server order into the local read model.
+ *
+ * Unlike `insertOrder` (which is HLC-guarded for local/LAN writes), the
+ * server copy is authoritative: it always overwrites the row. The only
+ * exception is an order with unsynced local work — its status and payment
+ * stay as the device intended until the queued command is acknowledged.
+ *
+ * The HLC is taken from the server's own `updated_at` so device clock skew
+ * can never make a fresh server state look stale.
+ */
+export declare function upsertServerOrder(db: SQLiteDatabase, order: import("../types/api/seller.api").SellerOrder, opts?: {
+    preserveStatus?: boolean;
+    preservePayment?: boolean;
+}): Promise<void>;
 export declare function listOrders(db: SQLiteDatabase, businessId: string, filters?: {
     status?: string;
     q?: string;

package/dist/db/operations.js

@@ -2,6 +2,11 @@
  * Low-level SQLite operations for the command outbox and event journal.
  */
 import { syncLogger } from "../utils/sync-logger";
+import { getQueuedStatus } from "../utils/order-transitions";
+/** Target status a queued command will produce on the server. */
+function queuedStatusOf(commandType) {
+    return getQueuedStatus(commandType);
+}
 export async function insertCommand(db, input) {
     const { command, status = "pending" } = input;
     const now = new Date().toISOString();
@@ -193,7 +198,47 @@ function rowToDomainEvent(row) {
         timestamp: row.timestamp,
     };
 }
+const EMPTY_PAYMENT = {
+    is_paid: false,
+    reference: null,
+    amount_minor: null,
+    currency: null,
+    paid_at: null,
+};
+/**
+ * Effective payment of a stored order.
+ *
+ * `payment` (server payment summary) is the primary shape, but the order's
+ * own `paid_at` column wins when the server did not report a payment. Cash
+ * sales taken at a POS terminal only carry `paid_at` — no payment
+ * transaction — so reading the blob alone made them look unpaid.
+ */
+function paymentStateOf(row) {
+    let parsed = {};
+    if (row.payment) {
+        try {
+            const value = JSON.parse(row.payment);
+            if (value && typeof value === "object")
+                parsed = value;
+        }
+        catch { }
+    }
+    const payment = { ...EMPTY_PAYMENT, ...parsed };
+    const paidAt = payment.paid_at ?? row.paid_at ?? null;
+    const isPaid = payment.is_paid === true || !!paidAt;
+    return { payment: { ...payment, paid_at: paidAt, is_paid: isPaid }, isPaid, paidAt };
+}
+/** True when the order has any recorded payment. */
+export function isOrderPaid(order) {
+    if (!order)
+        return false;
+    if (order.is_paid === true || order.paid_at)
+        return true;
+    const payment = order.payment;
+    return payment?.is_paid === true || !!payment?.paid_at;
+}
 function orderRowToSellerOrder(row) {
+    const { payment, isPaid, paidAt } = paymentStateOf(row);
     return {
         id: row.id,
         business_id: row.business_id,
@@ -207,7 +252,7 @@ function orderRowToSellerOrder(row) {
         total_minor: row.total_minor,
         tax_minor: row.tax_minor,
         tax_lines: row.tax_lines ? JSON.parse(row.tax_lines) : [],
-        payment: row.payment ? JSON.parse(row.payment) : { is_paid: false, reference: null, amount_minor: null, currency: null, paid_at: null },
+        payment,
         customer_name: row.customer_name,
         customer_phone: row.customer_phone,
         pos_payment_method: row.pos_payment_method,
@@ -217,15 +262,15 @@ function orderRowToSellerOrder(row) {
         delivery_lat: null,
         delivery_lng: null,
         user: row.user ? JSON.parse(row.user) : null,
-        currency: (row.payment ? JSON.parse(row.payment).currency : "GHS") ?? "GHS",
-        currency_code: (row.payment ? JSON.parse(row.payment).currency : "GHS") ?? "GHS",
+        currency: payment.currency ?? "GHS",
+        currency_code: payment.currency ?? "GHS",
         discount_minor: 0,
         promo_code: null,
         tip_minor: null,
         delivery_fee_minor: 0,
         delivery_status: null,
-        is_paid: row.payment ? JSON.parse(row.payment).is_paid ?? false : false,
-        paid_at: row.payment ? JSON.parse(row.payment).paid_at ?? null : null,
+        is_paid: isPaid,
+        paid_at: paidAt,
         inserted_at: row.inserted_at,
         updated_at: row.updated_at ?? row.inserted_at,
         sync_failed_at: row.sync_failed_at ?? null,
@@ -235,16 +280,102 @@ function orderRowToSellerOrder(row) {
 export async function insertOrder(db, order) {
     const hlc = order.hlc ?? new Date().toISOString();
     const updatedAt = order.updated_at ?? order.inserted_at;
-    await db.runAsync(`INSERT INTO orders (id, business_id, order_number, callout_number, status, order_type, is_pos, items, subtotal_minor, total_minor, tax_minor, tax_lines, payment, customer_name, customer_phone, pos_payment_method, delivery_id, business, user, inserted_at, updated_at, hlc)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-     ON CONFLICT(id) DO UPDATE SET business_id=excluded.business_id, order_number=excluded.order_number, callout_number=excluded.callout_number, status=excluded.status, order_type=excluded.order_type, is_pos=excluded.is_pos, items=excluded.items, subtotal_minor=excluded.subtotal_minor, total_minor=excluded.total_minor, tax_minor=excluded.tax_minor, tax_lines=excluded.tax_lines, payment=excluded.payment, customer_name=excluded.customer_name, customer_phone=excluded.customer_phone, pos_payment_method=excluded.pos_payment_method, delivery_id=excluded.delivery_id, business=excluded.business, user=excluded.user, updated_at=excluded.updated_at, hlc=excluded.hlc, sync_failed_at=NULL, sync_error=NULL
-     WHERE excluded.hlc >= orders.hlc OR orders.hlc IS NULL;`, order.id, order.business_id, order.order_number, order.callout_number, order.status, order.order_type, order.is_pos ? 1 : 0, JSON.stringify(order.items), order.subtotal_minor, order.total_minor, order.tax_minor, JSON.stringify(order.tax_lines), JSON.stringify(order.payment), order.customer_name, order.customer_phone, order.pos_payment_method, order.delivery_id, order.business ? JSON.stringify(order.business) : null, order.user ? JSON.stringify(order.user) : null, order.inserted_at, updatedAt, hlc);
+    const paidAt = order.paid_at ??
+        order.payment?.paid_at ??
+        (isOrderPaid(order) ? updatedAt : null);
+    await db.runAsync(`INSERT INTO orders (id, business_id, order_number, callout_number, status, order_type, is_pos, items, subtotal_minor, total_minor, tax_minor, tax_lines, payment, paid_at, customer_name, customer_phone, pos_payment_method, delivery_id, business, user, inserted_at, updated_at, hlc)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET business_id=excluded.business_id, order_number=excluded.order_number, callout_number=excluded.callout_number, status=excluded.status, order_type=excluded.order_type, is_pos=excluded.is_pos, items=excluded.items, subtotal_minor=excluded.subtotal_minor, total_minor=excluded.total_minor, tax_minor=excluded.tax_minor, tax_lines=excluded.tax_lines, payment=excluded.payment, paid_at=COALESCE(excluded.paid_at, orders.paid_at), customer_name=excluded.customer_name, customer_phone=excluded.customer_phone, pos_payment_method=excluded.pos_payment_method, delivery_id=excluded.delivery_id, business=excluded.business, user=excluded.user, updated_at=excluded.updated_at, hlc=excluded.hlc, sync_failed_at=NULL, sync_error=NULL
+     WHERE excluded.hlc >= orders.hlc OR orders.hlc IS NULL;`, order.id, order.business_id, order.order_number, order.callout_number, order.status, order.order_type, order.is_pos ? 1 : 0, JSON.stringify(order.items), order.subtotal_minor, order.total_minor, order.tax_minor, JSON.stringify(order.tax_lines), JSON.stringify(order.payment), paidAt, order.customer_name, order.customer_phone, order.pos_payment_method, order.delivery_id, order.business ? JSON.stringify(order.business) : null, order.user ? JSON.stringify(order.user) : null, order.inserted_at, updatedAt, hlc);
     notifyDbChange(order.business_id, "orders");
 }
 export async function getOrderById(db, businessId, idOrNumber) {
     const row = await db.getFirstAsync(`SELECT * FROM orders WHERE business_id = ? AND (id = ? OR order_number = ?) LIMIT 1;`, businessId, idOrNumber, idOrNumber);
     return row ? orderRowToSellerOrder(row) : null;
 }
+export async function getPendingOrderIntent(db, businessId, orderId) {
+    const empty = { status: null, isPaid: false, hasPending: false };
+    try {
+        const rows = await db.getAllAsync(`SELECT command_type, payload FROM sync_jobs WHERE business_id = ? AND entity_id = ? AND status = 'pending' ORDER BY created_at ASC, rowid ASC;`, businessId, orderId);
+        if (!rows.length)
+            return empty;
+        let status = null;
+        let isPaid = false;
+        for (const row of rows) {
+            const commandType = row.command_type ?? "";
+            const target = queuedStatusOf(commandType);
+            if (target)
+                status = target;
+            if (commandType === "payment:confirm_cash" || commandType === "order:confirm_cash") {
+                isPaid = true;
+            }
+            // A cash sale is paid at the moment it is rung up — the queued create
+            // itself is the record of that intent. Without this, a pull landing
+            // before the create reaches the backend replaces the paid local row
+            // with the server's (older, unpaid) copy.
+            if (commandType === "order:create") {
+                try {
+                    const payload = row.payload ? JSON.parse(row.payload) : null;
+                    const method = payload?.pos_payment_method ?? "cash";
+                    if (method === "cash")
+                        isPaid = true;
+                }
+                catch { }
+            }
+        }
+        return { status, isPaid, hasPending: true };
+    }
+    catch {
+        return empty;
+    }
+}
+/**
+ * Write a server order into the local read model.
+ *
+ * Unlike `insertOrder` (which is HLC-guarded for local/LAN writes), the
+ * server copy is authoritative: it always overwrites the row. The only
+ * exception is an order with unsynced local work — its status and payment
+ * stay as the device intended until the queued command is acknowledged.
+ *
+ * The HLC is taken from the server's own `updated_at` so device clock skew
+ * can never make a fresh server state look stale.
+ */
+export async function upsertServerOrder(db, order, opts = {}) {
+    if (!order?.id || !order?.business_id)
+        return;
+    const existing = await getOrderById(db, order.business_id, order.id);
+    const status = opts.preserveStatus && existing ? existing.status : order.status;
+    const serverPayment = (order.payment ?? {});
+    const serverPaidAt = order.paid_at ?? serverPayment.paid_at ?? null;
+    const serverIsPaid = order.is_paid === true || !!serverPaidAt || serverPayment.is_paid === true;
+    let payment;
+    if (existing &&
+        (opts.preservePayment || (!serverIsPaid && isOrderPaid(existing)))) {
+        // Keep the device's payment. A pull must never un-pay an order: the
+        // server copy of a cash sale rung up moments ago can lag behind, and it
+        // used to reset the row to UNPAID until the create finished syncing.
+        payment = { ...existing.payment };
+    }
+    else {
+        payment = {
+            ...serverPayment,
+            is_paid: serverIsPaid,
+            paid_at: serverPaidAt,
+            amount_minor: serverPayment.amount_minor ?? order.total_minor ?? null,
+            currency: serverPayment.currency ?? order.currency_code ?? null,
+        };
+    }
+    const paidAt = payment.paid_at ?? null;
+    const hlc = order.hlc ??
+        order.updated_at ??
+        order.inserted_at ??
+        new Date().toISOString();
+    const updatedAt = order.updated_at ?? order.inserted_at;
+    await db.runAsync(`INSERT INTO orders (id, business_id, order_number, callout_number, status, order_type, is_pos, items, subtotal_minor, total_minor, tax_minor, tax_lines, payment, paid_at, customer_name, customer_phone, pos_payment_method, delivery_id, business, user, inserted_at, updated_at, hlc)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET business_id=excluded.business_id, order_number=excluded.order_number, callout_number=excluded.callout_number, status=excluded.status, order_type=excluded.order_type, is_pos=excluded.is_pos, items=excluded.items, subtotal_minor=excluded.subtotal_minor, total_minor=excluded.total_minor, tax_minor=excluded.tax_minor, tax_lines=excluded.tax_lines, payment=excluded.payment, paid_at=COALESCE(excluded.paid_at, orders.paid_at), customer_name=excluded.customer_name, customer_phone=excluded.customer_phone, pos_payment_method=excluded.pos_payment_method, delivery_id=excluded.delivery_id, business=excluded.business, user=excluded.user, updated_at=excluded.updated_at, hlc=excluded.hlc, sync_failed_at=NULL, sync_error=NULL;`, order.id, order.business_id, order.order_number, order.callout_number, status, order.order_type, order.is_pos ? 1 : 0, JSON.stringify(order.items ?? []), order.subtotal_minor ?? 0, order.total_minor ?? 0, order.tax_minor ?? 0, JSON.stringify(order.tax_lines ?? []), JSON.stringify(payment), paidAt, order.customer_name, order.customer_phone, order.pos_payment_method, order.delivery_id, order.business ? JSON.stringify(order.business) : null, order.user ? JSON.stringify(order.user) : null, order.inserted_at, updatedAt, hlc);
+    notifyDbChange(order.business_id, "orders");
+}
 export async function listOrders(db, businessId, filters, page = 1, pageSize = 20) {
     const where = ["business_id = ?"];
     const args = [businessId];
@@ -263,11 +394,13 @@ export async function listOrders(db, businessId, filters, page = 1, pageSize = 2
         where.push("order_type = ?");
         args.push(filters.order_type);
     }
+    // Paid means "the order has a payment timestamp" (cash at the till) or the
+    // payment blob says so (gateway payment) — mirroring the backend filter.
     if (filters?.is_paid === "paid") {
-        where.push("json_extract(payment, '$.is_paid') = 1");
+        where.push("(json_extract(payment, '$.is_paid') = 1 OR paid_at IS NOT NULL)");
     }
     else if (filters?.is_paid === "unpaid") {
-        where.push("(json_extract(payment, '$.is_paid') IS NULL OR json_extract(payment, '$.is_paid') = 0)");
+        where.push("(COALESCE(json_extract(payment, '$.is_paid'), 0) = 0 AND paid_at IS NULL)");
     }
     if (filters?.q) {
         where.push("(order_number LIKE ? OR customer_name LIKE ? OR customer_phone LIKE ?)");
@@ -311,7 +444,7 @@ export async function updateOrderPayment(db, businessId, orderId, patch) {
     if (!row)
         return;
     const payment = { ...row.payment, is_paid: patch.is_paid, paid_at: patch.paid_at };
-    await db.runAsync(`UPDATE orders SET payment = ?, hlc = ? WHERE business_id = ? AND (id = ? OR order_number = ?);`, JSON.stringify(payment), new Date().toISOString(), businessId, orderId, orderId);
+    await db.runAsync(`UPDATE orders SET payment = ?, paid_at = COALESCE(?, paid_at), hlc = ? WHERE business_id = ? AND (id = ? OR order_number = ?);`, JSON.stringify(payment), patch.is_paid ? patch.paid_at : null, new Date().toISOString(), businessId, orderId, orderId);
     notifyDbChange(businessId, "orders");
 }
 /**

package/dist/domain/orders/order-flow.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Business-configurable fulfilment flow for terminal / business-app orders.
+ *
+ * Buyer-placed online orders always use the full pipeline
+ * (accept → preparing → ready → completed). Orders rung up on a POS terminal
+ * or in the business app follow the business setting:
+ *
+ *   "staged" (default) — same pipeline as online orders.
+ *   "direct"           — the sale is completed the moment it is taken, so the
+ *                        order is born `delivered` and no pipeline buttons are
+ *                        offered.
+ *
+ * The setting lives on the business (`businesses.pos_order_flow`) and is
+ * cached in the `business:profile` reference record, so it is readable while
+ * offline.
+ */
+import type { SQLiteDatabase } from "../../adapters/sqlite";
+export type OrderFlowMode = "staged" | "direct";
+export declare const DEFAULT_ORDER_FLOW_MODE: OrderFlowMode;
+/** Coerce any server/local value into a known mode. */
+export declare function normalizeOrderFlowMode(value: unknown): OrderFlowMode;
+export declare function isDirectOrderFlow(value: unknown): boolean;
+/**
+ * Read `pos_order_flow` out of a `business:profile` payload. Accepts both the
+ * reference-data envelope (`{ data: {...} }`) and a bare profile object.
+ */
+export declare function orderFlowModeFromProfile(payload: unknown): OrderFlowMode;
+/**
+ * Cached business flow mode (works fully offline). Falls back to "staged" when
+ * the profile has never been synced — the safe, full-pipeline default.
+ */
+export declare function getBusinessOrderFlowMode(businessId: string, db?: SQLiteDatabase): Promise<OrderFlowMode>;
+/**
+ * Status a POS/business-app order starts in.
+ *
+ * Cash sales in direct flow are complete on creation. Anything that still
+ * needs money (mobile money / card) must stay `awaiting_payment` first — the
+ * backend moves it to `accepted` (staged) or `delivered` (direct) once the
+ * payment lands.
+ */
+export declare function initialPosOrderStatus(paymentMethod: string | null | undefined, mode: OrderFlowMode): "accepted" | "awaiting_payment" | "delivered";

package/dist/domain/orders/order-flow.js

@@ -0,0 +1,66 @@
+/**
+ * Business-configurable fulfilment flow for terminal / business-app orders.
+ *
+ * Buyer-placed online orders always use the full pipeline
+ * (accept → preparing → ready → completed). Orders rung up on a POS terminal
+ * or in the business app follow the business setting:
+ *
+ *   "staged" (default) — same pipeline as online orders.
+ *   "direct"           — the sale is completed the moment it is taken, so the
+ *                        order is born `delivered` and no pipeline buttons are
+ *                        offered.
+ *
+ * The setting lives on the business (`businesses.pos_order_flow`) and is
+ * cached in the `business:profile` reference record, so it is readable while
+ * offline.
+ */
+import { openSyncDatabase } from "../../db/connection";
+import { getReferenceData } from "../../reference/operations";
+export const DEFAULT_ORDER_FLOW_MODE = "staged";
+/** Coerce any server/local value into a known mode. */
+export function normalizeOrderFlowMode(value) {
+    return value === "direct" ? "direct" : DEFAULT_ORDER_FLOW_MODE;
+}
+export function isDirectOrderFlow(value) {
+    return normalizeOrderFlowMode(value) === "direct";
+}
+/**
+ * Read `pos_order_flow` out of a `business:profile` payload. Accepts both the
+ * reference-data envelope (`{ data: {...} }`) and a bare profile object.
+ */
+export function orderFlowModeFromProfile(payload) {
+    if (!payload || typeof payload !== "object")
+        return DEFAULT_ORDER_FLOW_MODE;
+    const record = payload;
+    return normalizeOrderFlowMode(record.data?.pos_order_flow ?? record.pos_order_flow);
+}
+/**
+ * Cached business flow mode (works fully offline). Falls back to "staged" when
+ * the profile has never been synced — the safe, full-pipeline default.
+ */
+export async function getBusinessOrderFlowMode(businessId, db) {
+    if (!businessId)
+        return DEFAULT_ORDER_FLOW_MODE;
+    try {
+        const connection = db ?? (await openSyncDatabase());
+        const record = await getReferenceData(connection, businessId, "business:profile");
+        return orderFlowModeFromProfile(record?.payload);
+    }
+    catch {
+        return DEFAULT_ORDER_FLOW_MODE;
+    }
+}
+/**
+ * Status a POS/business-app order starts in.
+ *
+ * Cash sales in direct flow are complete on creation. Anything that still
+ * needs money (mobile money / card) must stay `awaiting_payment` first — the
+ * backend moves it to `accepted` (staged) or `delivered` (direct) once the
+ * payment lands.
+ */
+export function initialPosOrderStatus(paymentMethod, mode) {
+    const method = paymentMethod ?? "cash";
+    if (method !== "cash")
+        return "awaiting_payment";
+    return mode === "direct" ? "delivered" : "accepted";
+}

package/dist/domain/orders/service.js

@@ -15,6 +15,7 @@ import { canTransition } from "../../utils/order-transitions";
 import { TRANSITION_ERROR_CODES, TransitionError } from "../../sync/transition-errors";
 import { validateOrderCreateInput } from "../../validation/offline";
 import { buildItemSnapshots, snapshotsToOrderLines } from "./snapshots";
+import { getBusinessOrderFlowMode, initialPosOrderStatus } from "./order-flow";
 import { drainOne, pullRemoteOrders } from "../../sync/sync-jobs.service";
 import { getAuthToken } from "../../adapters/auth";
 import { canBusinessSync } from "../../sync/sync-guard";
@@ -78,6 +79,10 @@ export async function createLocalOrder(businessId, input) {
     // Offline validation mirror — backend Order.changeset rules, pre-commit.
     validateOrderCreateInput(input);
     const method = input.pos_payment_method ?? "cash";
+    // Business-configurable fulfilment flow (cached business profile, offline).
+    // "direct" completes walk-in sales the moment they are rung up; "staged"
+    // keeps accept → preparing → ready → completed.
+    const flowMode = await getBusinessOrderFlowMode(businessId);
     // Operating-hours gate (fail-closed, offline-first): matches backend
     // validate_business_open. Throws BUSINESS_CLOSED / HOURS_NOT_SYNCED before
     // anything is written, so a doomed order never enters SQLite/sync_jobs.
@@ -101,7 +106,13 @@ export async function createLocalOrder(businessId, input) {
     if (!dd)
         throw new Error("No device number leased (99 max) — connect online once to lease DD");
     const id = (input.id ?? input.command_id ?? generateUUID());
-    const orderNumber = input.order_number?.toString() ?? generateOrderNumberForBusiness(businessId);
+    // Order numbers must be real strings. A non-string value used to be
+    // coerced with `.toString()`, which wrote "[object Object]" into the local
+    // DB and broke every lookup for that order.
+    const rawOrderNumber = input.order_number;
+    const orderNumber = typeof rawOrderNumber === "string" && /^[A-Za-z0-9-]{1,32}$/.test(rawOrderNumber)
+        ? rawOrderNumber
+        : generateOrderNumberForBusiness(businessId);
     const callout = parseInt(orderNumber.split("-")[2] ?? "0", 10) || 0;
     // Use client-provided timestamps for offline-first sync so records created
     // while offline retain their original creation time.
@@ -122,7 +133,7 @@ export async function createLocalOrder(businessId, input) {
         id,
         order_number: orderNumber,
         callout_number: callout,
-        status: isPos ? "accepted" : "pending",
+        status: isPos ? initialPosOrderStatus(method, flowMode) : "pending",
         order_type: input.order_type ?? "takeout",
         is_pos: isPos,
         customer_name: input.customer_name ?? null,
@@ -155,7 +166,7 @@ export async function createLocalOrder(businessId, input) {
     };
     const db = await openSyncDatabase();
     await insertOrder(db, order);
-    syncLogger.debug("DomainOrders", "createLocalOrder inserted", { businessId, id, orderNumber, isPos, connectivity: getConnectivityState(), hasToken: !!getAuthToken(), deviceNumber: dd });
+    syncLogger.debug("DomainOrders", "createLocalOrder inserted", { businessId, id, orderNumber, isPos, flowMode, status: order.status, connectivity: getConnectivityState(), hasToken: !!getAuthToken(), deviceNumber: dd });
     try {
         await db.runAsync(`INSERT OR IGNORE INTO sync_jobs (id, business_id, command_type, entity_id, payload, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'pending', ?, ?);`, id, businessId, "order:create", id, JSON.stringify({ ...input, order_number: orderNumber, id }), now, now);
         syncLogger.debug("DomainOrders", "sync_jobs enqueued", { businessId, id, command_type: "order:create" });
@@ -195,10 +206,19 @@ export async function transitionLocalOrder(businessId, orderId, action) {
     }
     try {
         const now = new Date().toISOString();
-        const jobId = generateUUID();
-        await db.runAsync(`INSERT OR IGNORE INTO sync_jobs (id, business_id, command_type, entity_id, payload, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'pending', ?, ?);`, jobId, businessId, `order:${action}`, orderId, JSON.stringify({ action, orderId }), now, now);
-        syncLogger.debug("DomainOrders", "transition sync_jobs enqueued", { businessId, orderId, action, jobId });
-        void drainOne(businessId, orderId).catch((e) => syncLogger.debug("DomainOrders", "drainOne after transition caught", { err: String(e) }));
+        const commandType = `order:${action}`;
+        // Coalesce duplicates: the same transition queued twice (double tap,
+        // replay) must not be sent to the backend twice.
+        const duplicate = await db.getFirstAsync(`SELECT id FROM sync_jobs WHERE business_id = ? AND entity_id = ? AND command_type = ? AND status = 'pending' LIMIT 1;`, businessId, orderId, commandType);
+        if (!duplicate) {
+            const jobId = generateUUID();
+            await db.runAsync(`INSERT OR IGNORE INTO sync_jobs (id, business_id, command_type, entity_id, payload, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'pending', ?, ?);`, jobId, businessId, commandType, orderId, JSON.stringify({ action, orderId }), now, now);
+            syncLogger.debug("DomainOrders", "transition sync_jobs enqueued", { businessId, orderId, action, jobId });
+            void drainOne(businessId, orderId).catch((e) => syncLogger.debug("DomainOrders", "drainOne after transition caught", { err: String(e) }));
+        }
+        else {
+            syncLogger.debug("DomainOrders", "transition already queued — job not duplicated", { businessId, orderId, action, jobId: duplicate.id });
+        }
     }
     catch (e) {
         syncLogger.debug("DomainOrders", "transition enqueue fail", { err: String(e) });
@@ -215,15 +235,12 @@ export async function listLocalOrders(businessId, filters, page = 1, pageSize =
     const db = await openSyncDatabase();
     const res = await listOrders(db, businessId, filters, page, pageSize);
     if (res.total === 0) {
-        // blank-screen: snapshot fallback already tried — if still empty and online, fetch from cloud now so listing populates without manual refresh
+        // Cold device (no local rows yet): fetch in the BACKGROUND. Blocking the
+        // render on a multi-page network pull froze the screen for seconds on a
+        // fresh terminal; the pull writes to SQLite and the reconciliation
+        // bridge refreshes the list when it lands.
         if (isOnline() && canBusinessSync(businessId)) {
-            try {
-                await pullRemoteOrders(businessId);
-            }
-            catch { }
-            const afterPull = await listOrders(db, businessId, filters, page, pageSize);
-            if (afterPull.total > 0)
-                return afterPull;
+            void pullRemoteOrders(businessId).catch((e) => syncLogger.debug("DomainOrders", "background pull failed", { businessId, err: String(e) }));
         }
         // filtered miss — still try backfill re-read
         if (!filters || Object.keys(filters).length === 0) {

package/dist/hooks/realtime-stubs.d.ts

@@ -1,28 +1,35 @@
 /**
- * Realtime invalidation hooks — bridge Phoenix WebSocket events into the
- * Sync Engine so useSyncReconciliation fires and React Query caches refresh.
+ * Realtime invalidation hooks.
  *
- * Both hooks are idempotent-safe and can be called from multiple screens.
- * Invalidations are debounced: a reconnect/replay burst can deliver dozens
+ * The cloud → local event path now has a single owner: the global realtime
+ * bridge (`src/realtime/realtime-bridge.ts`), mounted once per app. It
+ * publishes every cloud event through the Sync Engine, and
+ * `useSyncReconciliation` reacts by journaling the event, patching the
+ * offline read model, invalidating the affected caches (debounced, 400 ms)
+ * and relaying the event to LAN peers.
+ *
+ * `useOrderRealtimeUpdates` used to be mounted per screen (POS, Orders,
+ * Kitchen, Display). That meant every mounted screen processed the same
+ * event — duplicated persistence, duplicated invalidations, duplicated
+ * fetches — and every screen that did NOT mount it (Dashboard, Settings)
+ * never saw another terminal's order at all. It is kept as a no-op so
+ * existing call sites keep compiling; new code must not use it.
+ *
+ * Invalidations stay coalesced: a reconnect/replay burst can deliver dozens
  * of events at once, and an immediate invalidate-per-event forces repeated
- * full re-renders of boards/grids — a major CPU spike source on low-power
- * POS hardware. Coalescing into one invalidation per ~400ms window keeps
- * the UI fresh without the render storm.
+ * full re-renders of boards/grids — a major CPU spike on low-power POS
+ * hardware. One invalidation per ~400 ms window keeps the UI fresh without
+ * the render storm.
  */
 /**
- * Subscribe to real-time order events and invalidate all queries under the
- * given root key prefix (e.g. ['seller'], ['pos'], ['kiosk']).
- *
- * Each event is also persisted to the durable offline read model so order
- * history and states survive a restart while offline, and published through
- * the Sync Engine so useSyncReconciliation + LAN relay fire without polling.
- *
- * Call once per screen that needs live updates (POS, Orders, Kitchen, etc.).
+ * @deprecated Mount the global bridge once at the app root instead
+ * (`useRealtimeInvalidation` or `useSyncReconciliation`). Kept as a no-op
+ * so legacy call sites remain source-compatible.
  */
-export declare function useOrderRealtimeUpdates(rootKey: readonly string[]): void;
+export declare function useOrderRealtimeUpdates(_rootKey: readonly string[]): void;
 /**
- * Global realtime invalidation — currently handled entirely by
- * useOrderRealtimeUpdates + useSyncReconciliation. Kept as a no-op for
- * backward compatibility with any lingering call sites.
+ * Global realtime invalidation — mounts the single app-wide Phoenix
+ * subscription. Pair with `useSyncReconciliation` (which reacts to the
+ * published events) at the app root.
  */
 export declare function useRealtimeInvalidation(): void;