@teincfood/core 0.9.22 → 0.9.24

package/dist/realtime/realtime-bridge.js

@@ -0,0 +1,149 @@
+/**
+ * Global realtime bridge — ONE Phoenix subscription for the whole app.
+ *
+ * Before this module existed, cloud events were only processed by screens
+ * that mounted `useOrderRealtimeUpdates` (POS, Orders, Kitchen, Display).
+ * Any other screen — the Dashboard, Settings, the business switcher — never
+ * saw another terminal's order, and every mounted screen duplicated the
+ * same handling (one persist + publish + invalidate per screen).
+ *
+ * The bridge is the single owner of the cloud → local event path:
+ *
+ *   Phoenix frame
+ *     → orderEventsService (typed event fan-out)
+ *       → business filter (active business only)
+ *         → syncEngine.publish(domainEvent)
+ *             → useSyncReconciliation: journal + read-model patch +
+ *               debounced query invalidation (+ LAN relay for mesh peers)
+ *         → unknown `order.created` → fetch THAT order only
+ *
+ * Mounting it from several hooks is safe: the underlying subscription is
+ * created once and torn down when the last consumer unmounts.
+ */
+import { useEffect } from "react";
+import { orderEventsService } from "./order-events.service";
+import { syncEngine } from "../sync/engine";
+import { getActiveBusiness } from "../adapters/business";
+import { getAppInstanceId } from "../adapters/devices";
+import { generateEventId } from "../utils/uuid";
+import { openSyncDatabase } from "../db/connection";
+import { getOrderById } from "../db/operations";
+import { fetchRemoteOrderByNumber } from "../sync/sync-jobs.service";
+import { syncLogger } from "../utils/sync-logger";
+/** Coalesce bursts of `order.created` events into one fetch per order. */
+const UNKNOWN_ORDER_FETCH_DEBOUNCE_MS = 400;
+let consumerCount = 0;
+let detach = null;
+/**
+ * Subscribe to the global realtime bridge.
+ * Safe to call from multiple hooks — the underlying socket listener is
+ * created once and disposed when the last caller releases it.
+ */
+export function subscribeGlobalRealtime() {
+    consumerCount += 1;
+    if (!detach)
+        detach = attachBridge();
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        consumerCount -= 1;
+        if (consumerCount <= 0) {
+            consumerCount = 0;
+            try {
+                detach?.();
+            }
+            catch { }
+            detach = null;
+        }
+    };
+}
+/** React hook wrapper around `subscribeGlobalRealtime`. */
+export function useGlobalRealtimeBridge() {
+    useEffect(() => subscribeGlobalRealtime(), []);
+}
+function attachBridge() {
+    const pendingFetches = new Map();
+    const scheduleUnknownOrderFetch = (businessId, orderNumber, orderId) => {
+        if (!businessId || (!orderNumber && !orderId))
+            return;
+        const key = `${businessId}:${orderNumber ?? orderId}`;
+        if (pendingFetches.has(key))
+            return;
+        const timer = setTimeout(() => {
+            pendingFetches.delete(key);
+            void (async () => {
+                try {
+                    // Only fetch when this device has never seen the order — the
+                    // realtime payload is summary-only, so a known order needs no
+                    // network call at all.
+                    if (orderId) {
+                        const db = await openSyncDatabase();
+                        const known = await getOrderById(db, businessId, orderId);
+                        if (known)
+                            return;
+                    }
+                    if (!orderNumber)
+                        return;
+                    await fetchRemoteOrderByNumber(businessId, orderNumber);
+                }
+                catch { }
+            })();
+        }, UNKNOWN_ORDER_FETCH_DEBOUNCE_MS);
+        pendingFetches.set(key, timer);
+    };
+    const unsubscribe = orderEventsService.onOrderUpdates((event) => {
+        try {
+            const payload = { ...event };
+            const activeBusinessId = getActiveBusiness()?.id;
+            let businessId = payload.business_id ??
+                payload.businessId;
+            // Delivery events carry no business id — the socket already filtered by
+            // business, so stamp the active one for read-model patching.
+            if (!businessId && activeBusinessId) {
+                businessId = activeBusinessId;
+                payload.business_id = activeBusinessId;
+            }
+            if (!businessId)
+                return;
+            // Never let another business' event touch this device.
+            if (activeBusinessId && businessId !== activeBusinessId)
+                return;
+            const ownDeviceId = getAppInstanceId();
+            const domainEvent = {
+                event_id: payload.event_id ?? generateEventId(),
+                event_type: event.type,
+                event_version: payload.event_version ?? "1.0",
+                timestamp: payload.timestamp ?? new Date().toISOString(),
+                device_id: payload.device_id ?? ownDeviceId,
+                user_id: payload.user_id ?? "system",
+                entity_id: event.order_id ?? "",
+                payload,
+                origin: "cloud",
+            };
+            // Publish through the Sync Engine: the reconciliation bridge journals
+            // the event, patches the offline read model, invalidates the caches and
+            // relays the event to LAN peers.
+            syncEngine.publish(domainEvent);
+            // An order created on another terminal arrives as a summary only, so
+            // this device has no row for it — fetch that single order (not the
+            // whole list) so the board fills in.
+            if (event.type === "order.created") {
+                scheduleUnknownOrderFetch(businessId, payload.order_number ??
+                    payload.local_order_number, event.order_id);
+            }
+        }
+        catch (error) {
+            syncLogger.warn("RealtimeBridge", "Failed to handle cloud event", {
+                error: String(error),
+            });
+        }
+    });
+    return () => {
+        for (const timer of pendingFetches.values())
+            clearTimeout(timer);
+        pendingFetches.clear();
+        unsubscribe();
+    };
+}

package/dist/reference/events.d.ts

@@ -45,7 +45,7 @@ export declare function emitReferenceChanged(businessId: string, keys: Reference
  * by a single-flight flag. Errors are logged, never thrown, so a failed
  * reference sync can never crash the LAN event loop.
  */
-export declare function applyReferenceChangeEvent(event: DomainEvent, origin?: "local" | "lan"): Promise<void>;
+export declare function applyReferenceChangeEvent(event: DomainEvent, origin?: "local" | "lan" | "cloud"): Promise<void>;
 /**
  * Best-effort reference data sync when connectivity recovers. Covers devices
  * that missed the change event (offline, not on the LAN) — the next time they

package/dist/reference/service.d.ts

@@ -9,8 +9,17 @@
  */
 import type { ReferenceDataKey, ReferenceSyncOptions, ReferenceSyncResult, ReferenceDataRecord } from "./types";
 declare class ReferenceSyncService {
-    private isSyncing;
+    /** Single-flight per business (a global flag made a business switch skip its sync). */
+    private inflight;
+    /**
+     * Keys requested while a pass was already running for that business.
+     * They used to be dropped, which meant a menu edit could land while
+     * another reference sync was in flight and never be fetched.
+     */
+    private queued;
     sync(options: ReferenceSyncOptions): Promise<ReferenceSyncResult>;
+    private rememberRequest;
+    private runSync;
     private syncKey;
     private fetchFallback;
     /**

package/dist/reference/service.js

@@ -38,12 +38,20 @@ const DEFAULT_SYNC_KEYS = [
 ];
 class ReferenceSyncService {
     constructor() {
-        this.isSyncing = false;
+        /** Single-flight per business (a global flag made a business switch skip its sync). */
+        this.inflight = new Map();
+        /**
+         * Keys requested while a pass was already running for that business.
+         * They used to be dropped, which meant a menu edit could land while
+         * another reference sync was in flight and never be fetched.
+         */
+        this.queued = new Map();
     }
     async sync(options) {
-        if (!canBusinessSync(options.businessId)) {
+        const businessId = options.businessId;
+        if (!canBusinessSync(businessId)) {
             syncLogger.debug("ReferenceSync", "Skipping sync — no business/auth", {
-                businessId: options.businessId,
+                businessId,
             });
             return {
                 synced: [],
@@ -52,18 +60,71 @@ class ReferenceSyncService {
                 errors: {},
             };
         }
-        if (this.isSyncing) {
-            return {
-                synced: [],
-                skipped: [],
-                failed: [],
-                errors: {},
-            };
+        const running = this.inflight.get(businessId);
+        if (running) {
+            // Remember the request so it is not lost, then wait for the pass that
+            // is already running.
+            this.rememberRequest(businessId, options.keys);
+            try {
+                return await running;
+            }
+            catch {
+                return { synced: [], skipped: [], failed: [], errors: {} };
+            }
+        }
+        const pass = (async () => {
+            try {
+                return await this.runSync(options);
+            }
+            finally {
+                this.inflight.delete(businessId);
+            }
+        })();
+        this.inflight.set(businessId, pass);
+        let result;
+        try {
+            result = await pass;
+        }
+        catch (error) {
+            syncLogger.warn("ReferenceSync", "Sync pass failed", { businessId, error: String(error) });
+            result = { synced: [], skipped: [], failed: [], errors: {} };
+        }
+        // Requests that arrived during the pass are served by one follow-up
+        // pass — never silently dropped.
+        const queued = this.queued.get(businessId);
+        if (queued && queued.size > 0) {
+            this.queued.delete(businessId);
+            const wantsAll = queued.has("*");
+            const keys = Array.from(queued).filter((k) => k !== "*");
+            const followUp = wantsAll
+                ? { businessId }
+                : { businessId, keys, incremental: true };
+            syncLogger.info("ReferenceSync", "Running follow-up pass for queued keys", {
+                businessId,
+                all: wantsAll,
+                keys,
+            });
+            await this.sync(followUp).catch(() => undefined);
+        }
+        return result;
+    }
+    rememberRequest(businessId, keys) {
+        const set = this.queued.get(businessId) ?? new Set();
+        if (!keys || keys.length === 0) {
+            set.add("*");
         }
+        else {
+            for (const key of keys)
+                set.add(key);
+        }
+        this.queued.set(businessId, set);
+    }
+    async runSync(options) {
+        const businessId = options.businessId;
         const { isOnline, isCloudReachable } = getConnectivityState();
         if (!isOnline || isCloudReachable === "unreachable") {
             syncLogger.debug("ReferenceSync", "Skipping sync — cloud not reachable", {
-                businessId: options.businessId,
+                businessId,
                 isOnline,
                 isCloudReachable,
             });
@@ -74,9 +135,8 @@ class ReferenceSyncService {
                 errors: {},
             };
         }
-        this.isSyncing = true;
         syncLogger.info("ReferenceSync", "Starting reference data sync", {
-            businessId: options.businessId,
+            businessId,
             keys: options.keys,
         });
         const result = {
@@ -145,13 +205,13 @@ class ReferenceSyncService {
             }
         }
         finally {
-            this.isSyncing = false;
+            syncLogger.info("ReferenceSync", "Reference data sync complete", {
+                businessId,
+                synced: result.synced,
+                skipped: result.skipped,
+                failed: result.failed,
+            });
         }
-        syncLogger.info("ReferenceSync", "Reference data sync complete", {
-            synced: result.synced,
-            skipped: result.skipped,
-            failed: result.failed,
-        });
         return result;
     }
     async syncKey(db, key, options, versions) {

package/dist/sync/command-queue.service.d.ts

@@ -50,11 +50,12 @@ declare class CommandQueueService {
      */
     private failDependentTransitions;
     /**
-     * Already-applied absorb: pull server truth, and if the order is already
-     * at this command's target status, delete the command as success. The
-     * absorb ONLY fires when the pull actually touched the row (hlc change) —
-     * otherwise a stale local optimistic write could mask a genuine race and
-     * delete work the server never applied.
+     * Already-applied absorb: the server already moved the order to this
+     * command's target status, so the queued command is redundant and can be
+     * dropped.
+     *
+     * The comparison uses the SERVER status reported by the pull — the local
+     * row may show this device's own queued intent and would absorb itself.
      */
     private absorbIfApplied;
     /**

package/dist/sync/command-queue.service.js

@@ -586,27 +586,23 @@ class CommandQueueService {
         catch { }
     }
     /**
-     * Already-applied absorb: pull server truth, and if the order is already
-     * at this command's target status, delete the command as success. The
-     * absorb ONLY fires when the pull actually touched the row (hlc change) —
-     * otherwise a stale local optimistic write could mask a genuine race and
-     * delete work the server never applied.
+     * Already-applied absorb: the server already moved the order to this
+     * command's target status, so the queued command is redundant and can be
+     * dropped.
+     *
+     * The comparison uses the SERVER status reported by the pull — the local
+     * row may show this device's own queued intent and would absorb itself.
      */
     async absorbIfApplied(command) {
         const target = QUEUED_STATUS_BY_COMMAND[command.command_type];
         if (!target || !command.entity_id)
             return false;
         try {
-            const db = getSyncDatabase();
-            const before = await db.getFirstAsync(`SELECT hlc FROM orders WHERE business_id = ? AND id = ?;`, command.business_id, command.entity_id);
             const { pullRemoteOrders } = await import("./sync-jobs.service");
-            await pullRemoteOrders(command.business_id);
-            const afterHlc = await db.getFirstAsync(`SELECT hlc FROM orders WHERE business_id = ? AND id = ?;`, command.business_id, command.entity_id);
-            if (!afterHlc || afterHlc.hlc === before?.hlc)
-                return false;
-            const { getOrderById } = await import("../db/operations");
-            const order = await getOrderById(db, command.business_id, command.entity_id);
-            if (order && order.status === target) {
+            const serverStatuses = await pullRemoteOrders(command.business_id);
+            const serverStatus = serverStatuses.get(command.entity_id);
+            if (serverStatus === target) {
+                const db = getSyncDatabase();
                 await deleteCommand(db, command.command_id);
                 retryNotBefore.delete(command.command_id);
                 syncLogger.info("CommandQueueService", "Transition already applied on server, absorbing", {

package/dist/sync/full-sync.js

@@ -17,7 +17,7 @@ import { syncLogger } from "../utils/sync-logger";
 import { referenceSyncService } from "../reference/service";
 import { pullRemoteOrders, drainPending } from "./sync-jobs.service";
 import { canBusinessSync } from "./sync-guard";
-let inFlight = null;
+const inFlight = new Map();
 export async function performFullSync(businessId) {
     const bid = businessId ?? getActiveBusiness()?.id;
     if (!bid || !canBusinessSync(bid))
@@ -25,9 +25,13 @@ export async function performFullSync(businessId) {
     const s = getConnectivityState();
     if (!s.isOnline || s.isCloudReachable === "unreachable")
         return;
-    if (inFlight) {
+    // Single-flight PER BUSINESS. A global in-flight promise meant that
+    // switching business while business A was syncing made business B join
+    // A's promise and return without syncing at all.
+    const running = inFlight.get(bid);
+    if (running) {
         try {
-            await inFlight;
+            await running;
         }
         catch { }
         return;
@@ -70,11 +74,11 @@ export async function performFullSync(businessId) {
             syncLogger.warn("FullSync", "Failed", { err: String(e) });
         }
     })();
-    inFlight = p;
+    inFlight.set(bid, p);
     try {
         await p;
     }
     finally {
-        inFlight = null;
+        inFlight.delete(bid);
     }
 }

package/dist/sync/order-merge.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Server → local order merge.
+ *
+ * The server is authoritative for an order — EXCEPT while this device still
+ * has unsynced work for it. A pull can land before the queued command
+ * reaches the backend (reconnect storms, slow networks, a second terminal
+ * pushing at the same time); without the overlay the local terminal would
+ * visibly revert an accepted order back to `pending`, or drop a confirmed
+ * cash payment, until the queue drained.
+ *
+ * Rules:
+ *   1. The server row always overwrites the local row (status, totals,
+ *      delivery linkage, items).
+ *   2. If this device has a pending command for the order, the local intent
+ *      (target status / payment) is re-applied on top of the server row.
+ *   3. The local HLC comes from the server's `updated_at`, so device clock
+ *      skew can never make fresh server state look stale.
+ */
+import type { SQLiteDatabase } from "../adapters/sqlite";
+import type { SellerOrder } from "../types/api/seller.api";
+/**
+ * Merge one server order into the local read model.
+ * Returns true when the row was written.
+ */
+export declare function mergeOrderFromServer(db: SQLiteDatabase, businessId: string, serverOrder: SellerOrder): Promise<boolean>;

package/dist/sync/order-merge.js

@@ -0,0 +1,61 @@
+/**
+ * Server → local order merge.
+ *
+ * The server is authoritative for an order — EXCEPT while this device still
+ * has unsynced work for it. A pull can land before the queued command
+ * reaches the backend (reconnect storms, slow networks, a second terminal
+ * pushing at the same time); without the overlay the local terminal would
+ * visibly revert an accepted order back to `pending`, or drop a confirmed
+ * cash payment, until the queue drained.
+ *
+ * Rules:
+ *   1. The server row always overwrites the local row (status, totals,
+ *      delivery linkage, items).
+ *   2. If this device has a pending command for the order, the local intent
+ *      (target status / payment) is re-applied on top of the server row.
+ *   3. The local HLC comes from the server's `updated_at`, so device clock
+ *      skew can never make fresh server state look stale.
+ */
+import { getOrderById, getPendingOrderIntent, updateOrderPayment, updateOrderStatus, upsertServerOrder, } from "../db/operations";
+import { syncLogger } from "../utils/sync-logger";
+/**
+ * Merge one server order into the local read model.
+ * Returns true when the row was written.
+ */
+export async function mergeOrderFromServer(db, businessId, serverOrder) {
+    if (!businessId || !serverOrder?.id)
+        return false;
+    try {
+        const intent = await getPendingOrderIntent(db, businessId, serverOrder.id);
+        await upsertServerOrder(db, { ...serverOrder, business_id: businessId });
+        if (intent.hasPending) {
+            if (intent.status) {
+                await updateOrderStatus(db, businessId, serverOrder.id, intent.status);
+            }
+            if (intent.isPaid) {
+                const local = await getOrderById(db, businessId, serverOrder.id);
+                const paidAt = local?.payment?.paid_at ??
+                    new Date().toISOString();
+                await updateOrderPayment(db, businessId, serverOrder.id, {
+                    is_paid: true,
+                    paid_at: paidAt,
+                });
+            }
+            syncLogger.debug("OrderMerge", "Applied local intent over server row", {
+                businessId,
+                orderId: serverOrder.id,
+                status: intent.status,
+                isPaid: intent.isPaid,
+            });
+        }
+        return true;
+    }
+    catch (error) {
+        syncLogger.warn("OrderMerge", "Failed to merge server order", {
+            businessId,
+            orderId: serverOrder?.id,
+            error: String(error),
+        });
+        return false;
+    }
+}

package/dist/sync/pending-orders.service.d.ts

@@ -59,5 +59,5 @@ export declare function hydratePendingOrders(): Promise<void>;
  * pending-orders store (only queued creations are); this only fires the
  * invalidator. Idempotent — duplicate deliveries are harmless.
  */
-export declare function applyOrderStateChangeEvent(event: DomainEvent, origin?: "local" | "lan"): Promise<void>;
-export declare function applyPendingOrderEvent(event: DomainEvent, origin?: "local" | "lan"): Promise<void>;
+export declare function applyOrderStateChangeEvent(event: DomainEvent, origin?: "local" | "lan" | "cloud"): Promise<void>;
+export declare function applyPendingOrderEvent(event: DomainEvent, origin?: "local" | "lan" | "cloud"): Promise<void>;

package/dist/sync/sync-jobs.service.d.ts

@@ -4,7 +4,28 @@
  * Core-only, single in_flight per business, coalesced via isOnline gate.
  */
 export declare function drainOne(businessId: string, entityId: string): Promise<void>;
-export declare function pullRemoteOrders(businessId: string): Promise<void>;
+/**
+ * Pull the server's recent orders into the local read model.
+ *
+ * Returns the SERVER status per order id. The local row can show a
+ * different status (a queued transition keeps the device's intent on top of
+ * the server copy), so a caller that needs to know what the server actually
+ * holds must read it from this map — never from the merged local row.
+ */
+export declare function pullRemoteOrders(businessId: string): Promise<Map<string, string>>;
+/**
+ * Fetch exactly ONE order from the server and merge it into the local
+ * read model.
+ *
+ * Used when a realtime `order.created` event arrives for an order this
+ * device has never seen: the event carries only a summary, so the order has
+ * to be fetched — but fetching the whole list (100 orders, several pages,
+ * heavy serialization) for one new order is pure waste on the backend.
+ *
+ * Uses the existing business-scoped list endpoint with an `order_number`
+ * filter, so no backend change is required.
+ */
+export declare function fetchRemoteOrderByNumber(businessId: string, orderNumber: string): Promise<boolean>;
 export declare function drainPending(businessId: string): Promise<void>;
 export declare function setupSyncJobsDrain(): void;
 export declare function getSyncJobsPendingCount(businessId: string): Promise<number>;