@teincfood/core 0.7.9 → 0.8.0

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

@@ -11,8 +11,9 @@
 import { getSyncDatabase, openSyncDatabase } from "../db/connection";
 import { insertCommand, getPendingCommands, markCommandInFlight, updateCommandStatus, deleteCommand, insertEvent, } from "../db/operations";
 import { syncLogger } from "../utils/sync-logger";
+import { recordAttempt } from "../utils/attempt-stats";
 import { generateEventId } from "../utils/uuid";
-import { generateLocalCalloutNumber, generateOrderNumberForBusiness, } from "./order-number";
+import { generateLocalCalloutNumber, generateOrderNumberForBusiness, generateOrderNumber, } from "./order-number";
 import { getConnectivityState, subscribeConnectivity } from "../adapters/connectivity";
 const MAX_RETRIES = 5;
 const QUEUED_STATUS_BY_COMMAND = {
@@ -98,14 +99,14 @@ function buildOptimisticOrder(command, payload) {
     return {
         id: command.entity_id ?? command.command_id,
         order_number: orderNumber,
-        callout_number: generateLocalCalloutNumber(),
+        callout_number: generateLocalCalloutNumber(command.business_id),
         order_type: payload.order_type ?? "takeout",
         is_pos: true,
         customer_name: payload.customer_name ?? null,
         customer_phone: payload.customer_phone ?? null,
         pos_payment_method: payload.pos_payment_method ?? "cash",
         paid_at: null,
-        status: "pending",
+        status: "accepted",
         delivery_id: null,
         delivery_status: null,
         is_paid: payload.pos_payment_method === "cash",
@@ -174,7 +175,7 @@ function injectLocalOrderNumber(command) {
 }
 class CommandQueueService {
     constructor() {
-        this.replaying = false;
+        this.replaying = null;
         this.syncEngine = null;
     }
     setSyncEngine(engine) {
@@ -254,7 +255,7 @@ class CommandQueueService {
         }
         await markCommandInFlight(db, command.command_id);
         try {
-            const events = await this.syncEngine.execute(parsedCommand);
+            const events = await this.syncEngine.execute(parsedCommand, { forReplay: true });
             // Outbox is an ephemeral queue — remove the row on success so the
             // Diagnostics outbox count drops to 0 and old completed rows never
             // accumulate. The optimistic event stays in `events` (marked synced).
@@ -270,11 +271,18 @@ class CommandQueueService {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
+            // Replay with no transport available: leave the row exactly as-is for
+            // the next trigger (do not mark, do not count). Must reset the
+            // in_flight flag first — rows stuck in_flight are invisible to the
+            // outbox query and would wedge the queue forever.
+            if (message.includes("ReplayDeferred")) {
+                await updateCommandStatus(db, command.command_id, "pending", "deferred:no-transport");
+                throw error;
+            }
             const apiErr = error;
             // 409 ORDER_NUMBER_TAKEN is retryable once with new RRR
             const code = apiErr?.code ?? apiErr?.data?.code;
             if (apiErr?.status === 409 && String(code).includes("ORDER_NUMBER_TAKEN")) {
-                // Regenerate random part of order_number if this was order:create
                 if (command.command_type === "order:create") {
                     try {
                         const payload = command.payload;
@@ -282,12 +290,14 @@ class CommandQueueService {
                         const parsed = on ? on.match(/^([0-9]{2})-([0-9]{3})-([0-9]{3})$/) : null;
                         if (parsed) {
                             const deviceNumber = parsed[1];
-                            const { generateOrderNumber } = await import("./order-number");
-                            const { orderNumber: newOn } = generateOrderNumber(deviceNumber);
+                            const { orderNumber: newOn } = generateOrderNumber(deviceNumber, command.business_id);
                             const newPayload = { ...payload, order_number: newOn };
-                            await updateCommandStatus(db, command.command_id, "failed", `retry_random:${message}`);
-                            // Update stored payload for retry
-                            await db.runAsync(`UPDATE commands SET payload = ?, retry_count = retry_count WHERE command_id = ?;`, JSON.stringify(newPayload), command.command_id);
+                            await db.runAsync(`UPDATE commands SET payload = ?, error = ?, updated_at = ? WHERE command_id = ?;`, JSON.stringify(newPayload), `retry_random:${message}`, new Date().toISOString(), command.command_id);
+                            syncLogger.info("CommandQueueService", "Regenerated order_number after 409", { command_id: command.command_id, new_order_number: newOn });
+                            // keep retry_count unchanged so next replay retries; do not mark failed twice.
+                            // Reset in_flight → pending so the row stays visible to the outbox query.
+                            await updateCommandStatus(db, command.command_id, "pending", `retry_random:${message}`);
+                            return;
                         }
                     }
                     catch { }
@@ -307,11 +317,29 @@ class CommandQueueService {
                     status: apiErr.status,
                     error: message,
                 });
+                // Loud toast + revert: the optimistic local write is rolled back so
+                // the UI never shows what the backend refused.
+                try {
+                    const { notifyError } = await import("../adapters/notify");
+                    notifyError(`Server rejected ${command.command_type}: ${message}`);
+                }
+                catch { }
+                try {
+                    if (command.command_type.startsWith("menu:") && command.entity_id) {
+                        const { revertMenuCommand } = await import("../reference/menu-apply");
+                        await revertMenuCommand(command.business_id, command.command_type, command.entity_id);
+                    }
+                }
+                catch { }
                 // Do not throw — allow replay to continue to next command.
                 return;
             }
-            await updateCommandStatus(db, command.command_id, "failed", message);
-            syncLogger.command(parsedCommand, "failed", { error: message });
+            // Network/timeout/5xx: NOT a rejection — keep the command retryable
+            // indefinitely (status back to pending, retry_count untouched) so a
+            // long outage never dead-letters the outbox via MAX_RETRIES. Replay
+            // stops here to preserve ordering; the next trigger retries.
+            await updateCommandStatus(db, command.command_id, "pending", `network:${message}`);
+            syncLogger.command(parsedCommand, "queued", { error: message, deferred: true });
             throw error;
         }
     }
@@ -320,11 +348,21 @@ class CommandQueueService {
      * ordering consistent; the next replay will retry from the failed command.
      */
     async replay() {
+        recordAttempt("sync_drain", "replay");
+        // Join an in-flight replay instead of no-op'ing: concurrent replays
+        // (connectivity auto-replay racing an explicit replay) must converge on
+        // the same outcome, otherwise callers observe a drained queue while work
+        // is still flying.
         if (this.replaying) {
-            syncLogger.debug("CommandQueueService", "Replay already in progress");
+            syncLogger.debug("CommandQueueService", "Replay already in progress, joining");
+            try {
+                await this.replaying;
+            }
+            catch { }
             return;
         }
-        this.replaying = true;
+        let resolveReplay;
+        this.replaying = new Promise((r) => { resolveReplay = r; });
         try {
             // Await open (not getSyncDatabase) so a cold-start replay triggered by a
             // connectivity event that fires before the DB open completes does not
@@ -356,7 +394,11 @@ class CommandQueueService {
             }
         }
         finally {
-            this.replaying = false;
+            this.replaying = null;
+            try {
+                resolveReplay();
+            }
+            catch { }
         }
     }
     /**
@@ -377,5 +419,28 @@ class CommandQueueService {
         const commands = await getPendingCommands(db, Number.MAX_SAFE_INTEGER);
         return commands.length;
     }
+    /**
+     * Debug dump of the engine outbox for Diagnostics screens (all statuses,
+     * newest last). Mirrors debugDumpSyncJobs.
+     */
+    async debugDumpCommands(businessId) {
+        try {
+            const db = getSyncDatabase();
+            const rows = await getPendingCommands(db, Number.MAX_SAFE_INTEGER);
+            return rows
+                .filter((c) => !businessId || c.business_id === businessId)
+                .map((c) => ({
+                id: c.command_id,
+                command_type: c.command_type,
+                status: c.status,
+                retry_count: c.retry_count,
+                error: c.error ?? null,
+                created_at: c.created_at ?? "",
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
 }
 export const commandQueueService = new CommandQueueService();

package/dist/sync/device-lease.service.d.ts

@@ -3,7 +3,7 @@
  * Backend authority: POST /businesses/:id/devices/lease
  * KV persists device_number per businessId.
  */
-declare function getAppInstanceId(): string;
+import { getAppInstanceIdAsync } from "../adapters/devices";
 export declare function getDeviceNumber(businessId: string): string | null;
 export declare function isOnlineOnly(businessId: string): boolean;
 export declare function ensureLease(businessId: string): Promise<string | null>;
@@ -14,6 +14,6 @@ export declare const deviceLeaseService: {
     isOnlineOnly: typeof isOnlineOnly;
     ensureLease: typeof ensureLease;
     refreshLease: typeof refreshLease;
-    getAppInstanceId: typeof getAppInstanceId;
+    getAppInstanceId: typeof getAppInstanceIdAsync;
+    getAppInstanceIdAsync: typeof getAppInstanceIdAsync;
 };
-export {};

package/dist/sync/device-lease.service.js

@@ -3,20 +3,13 @@
  * Backend authority: POST /businesses/:id/devices/lease
  * KV persists device_number per businessId.
  */
-import { getItemSync as getSync, setItemSync as setSync } from "../adapters/kv";
+import { getItemSync as getSync, setItemSync as setSync, removeItemSync, getItem } from "../adapters/kv";
 import { getHttpClient } from "../adapters/http";
-import { generateUUID } from "../utils/uuid";
 import { syncLogger } from "../utils/sync-logger";
+import { getAppInstanceIdAsync } from "../adapters/devices";
+import { getConnectivityState } from "../adapters/connectivity";
 const LEASE_KEY = (businessId) => `teinc_device_number:${businessId}`;
 const LEASE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
-function getAppInstanceId() {
-    let id = getSync("teinc_app_instance_id");
-    if (!id) {
-        id = generateUUID();
-        setSync("teinc_app_instance_id", id);
-    }
-    return id;
-}
 export function getDeviceNumber(businessId) {
     const v = getSync(LEASE_KEY(businessId));
     if (v && /^(0[1-9]|[1-9][0-9])$/.test(v))
@@ -27,32 +20,99 @@ export function isOnlineOnly(businessId) {
     return getDeviceNumber(businessId) == null;
 }
 export async function ensureLease(businessId) {
-    const existing = getDeviceNumber(businessId);
-    if (existing)
-        return existing;
+    // Offline-first: keep leased DD even offline — if online check/lease fails, return cached
+    const existingSync = getDeviceNumber(businessId);
+    if (existingSync) {
+        // Opportunistically refresh touch if online, but never discard cached on failure
+        if (getConnectivityState().isOnline) {
+            try {
+                const leasedAt = getSync(`${LEASE_KEY(businessId)}:leased_at`);
+                const needsRefresh = !leasedAt || Date.now() - new Date(leasedAt).getTime() > LEASE_TTL_MS - 24 * 60 * 60 * 1000;
+                if (needsRefresh)
+                    await refreshLease(businessId);
+            }
+            catch {
+                // keep existing on any refresh failure
+            }
+        }
+        return existingSync;
+    }
+    // No sync cache — try async KV (covers boot race where sync cache not yet hydrated from kv.json)
+    try {
+        const asyncCached = await getItem(LEASE_KEY(businessId));
+        if (asyncCached && /^(0[1-9]|[1-9][0-9])$/.test(asyncCached)) {
+            // hydrate sync cache for next getDeviceNumber calls
+            try {
+                setSync(LEASE_KEY(businessId), asyncCached);
+            }
+            catch { }
+            return asyncCached;
+        }
+    }
+    catch { }
+    // No cached DD — must lease online. If offline, keep null (caller blocks POS with clear message)
+    if (!getConnectivityState().isOnline) {
+        syncLogger.debug("DeviceLease", "Offline and no cached DD — need online once", { businessId });
+        return null;
+    }
     try {
         const http = getHttpClient();
-        const deviceUuid = getAppInstanceId();
+        const deviceUuid = await getAppInstanceIdAsync();
         const res = await http.post(`/businesses/${businessId}/devices/lease`, { device_uuid: deviceUuid, app_instance_id: deviceUuid });
         const data = res.data?.data ?? res.data;
         const dn = data.device_number;
         if (dn && /^(0[1-9]|[1-9][0-9])$/.test(dn)) {
             setSync(LEASE_KEY(businessId), dn);
             setSync(`${LEASE_KEY(businessId)}:leased_at`, new Date().toISOString());
+            try {
+                await getItem(LEASE_KEY(businessId));
+            }
+            catch { }
             syncLogger.info("DeviceLease", "Leased device number", { businessId, device_number: dn });
             return dn;
         }
     }
     catch (e) {
         const apiErr = e;
-        if (apiErr?.status === 429 || e?.message?.includes("DEVICE_LIMIT_REACHED")) {
+        const msg = String(e?.message ?? "");
+        const isAuth = apiErr?.status === 401 || msg.includes("TOKEN_MISSING") || msg.includes("No authentication token");
+        if (isAuth) {
+            syncLogger.debug("DeviceLease", "No auth yet — lease deferred until login", { businessId });
+            // fallback to any async cache that may have appeared concurrently
+            try {
+                const fallback = await getItem(LEASE_KEY(businessId));
+                if (fallback && /^(0[1-9]|[1-9][0-9])$/.test(fallback))
+                    return fallback;
+            }
+            catch { }
+            const again = getDeviceNumber(businessId);
+            if (again)
+                return again;
+            return null;
+        }
+        if (apiErr?.status === 429 || msg.includes("DEVICE_LIMIT_REACHED")) {
             syncLogger.warn("DeviceLease", "Device limit reached — online only", { businessId });
             return null;
         }
-        syncLogger.warn("DeviceLease", "Lease failed — will operate online-only until next boot", {
+        // Network/offline failure while leasing — keep any cached that may exist
+        syncLogger.warn("DeviceLease", "Lease failed — keep cached if any", {
             businessId,
             error: String(e),
         });
+        try {
+            const fallback = await getItem(LEASE_KEY(businessId));
+            if (fallback && /^(0[1-9]|[1-9][0-9])$/.test(fallback)) {
+                try {
+                    setSync(LEASE_KEY(businessId), fallback);
+                }
+                catch { }
+                return fallback;
+            }
+        }
+        catch { }
+        const again = getDeviceNumber(businessId);
+        if (again)
+            return again;
     }
     return null;
 }
@@ -68,7 +128,8 @@ export async function refreshLease(businessId) {
     }
     try {
         const http = getHttpClient();
-        await http.patch(`/businesses/${businessId}/devices/${getAppInstanceId()}/touch`, {});
+        const uuid = await getAppInstanceIdAsync();
+        await http.patch(`/businesses/${businessId}/devices/${uuid}/touch`, {});
         setSync(`${LEASE_KEY(businessId)}:leased_at`, new Date().toISOString());
     }
     catch {
@@ -76,8 +137,6 @@ export async function refreshLease(businessId) {
     }
 }
 export function clearLeaseForTests(businessId) {
-    // test helper
-    const { removeItemSync } = require("../adapters/kv");
     removeItemSync(LEASE_KEY(businessId));
     removeItemSync(`${LEASE_KEY(businessId)}:leased_at`);
 }
@@ -86,5 +145,6 @@ export const deviceLeaseService = {
     isOnlineOnly,
     ensureLease,
     refreshLease,
-    getAppInstanceId,
+    getAppInstanceId: getAppInstanceIdAsync,
+    getAppInstanceIdAsync,
 };

package/dist/sync/engine.d.ts

@@ -32,7 +32,9 @@ export declare class SyncEngine {
      * internet connection falls back to the Local Node (or the offline outbox)
      * quickly instead of blocking the terminal for the full HTTP timeout.
      */
-    execute(command: Command): Promise<DomainEvent[]>;
+    execute(command: Command, opts?: {
+        forReplay?: boolean;
+    }): Promise<DomainEvent[]>;
     /**
      * Trigger replay of queued commands when connectivity returns.
      */

package/dist/sync/engine.js

@@ -18,6 +18,9 @@ import { getConnectivityState, setConnectivityState } from "../adapters/connecti
 import { ApiError } from "../adapters/http";
 import { syncLogger } from "../utils/sync-logger";
 import { CLOUD_COMMAND_TIMEOUT_MS } from "../utils/constants";
+import { CAPABILITY_BY_COMMAND } from "../reference/capabilities";
+import { getReferenceData } from "../reference/operations";
+import { openSyncDatabase } from "../db/connection";
 function withTimeout(promise, ms) {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
@@ -49,15 +52,12 @@ export class SyncEngine {
      * internet connection falls back to the Local Node (or the offline outbox)
      * quickly instead of blocking the terminal for the full HTTP timeout.
      */
-    async execute(command) {
+    async execute(command, opts) {
         syncLogger.command(command, "issued");
         // Perms guard (offline-capable): block before routing
-        const { CAPABILITY_BY_COMMAND } = await import("../reference/capabilities");
         const required = CAPABILITY_BY_COMMAND[command.command_type];
         if (required) {
             try {
-                const { getReferenceData } = await import("../reference/operations");
-                const { openSyncDatabase } = await import("../db/connection");
                 const db = await openSyncDatabase();
                 const rec = await getReferenceData(db, command.business_id, "capabilities");
                 const caps = rec?.payload?.data?.capabilities ?? [];
@@ -84,8 +84,42 @@ export class SyncEngine {
             lan_available: localNodeTransport.isAvailable(),
         });
         if (strategy === "queue") {
+            // Replays must never re-enqueue-then-delete (the command would eat
+            // itself without executing). If no real transport is available, leave
+            // the row untouched for a later trigger.
+            if (opts?.forReplay) {
+                throw new Error("ReplayDeferred: no transport available, keeping command queued");
+            }
             const event = await commandQueueService.enqueue(command);
             this.broadcast(event);
+            // Menu writes need a visible local effect while queued: patch the
+            // durable reference cache optimistically and fan out
+            // reference_data.changed so reconciliation applies it locally and
+            // relays it to LAN peers (replay re-applies idempotently; the backend
+            // owns versions on cloud convergence).
+            if (command.command_type.startsWith("menu:")) {
+                try {
+                    const { applyMenuCommandLocal } = await import("../reference/menu-apply");
+                    const { keys } = await applyMenuCommandLocal(command.business_id, command);
+                    if (keys.length) {
+                        const { REFERENCE_CHANGED_EVENT_TYPE } = await import("../reference/events");
+                        const { generateEventId } = await import("../utils/uuid");
+                        this.broadcast({
+                            event_id: generateEventId(),
+                            event_type: REFERENCE_CHANGED_EVENT_TYPE,
+                            event_version: "1.0",
+                            entity_id: command.business_id,
+                            user_id: command.user_id,
+                            device_id: command.device_id,
+                            payload: { business_id: command.business_id, keys },
+                            timestamp: new Date().toISOString(),
+                        });
+                    }
+                }
+                catch (e) {
+                    syncLogger.debug("SyncEngine", "queued menu optimistic apply failed", { err: String(e) });
+                }
+            }
             return [event];
         }
         if (strategy === "cloud") {
@@ -130,6 +164,12 @@ export class SyncEngine {
                 setConnectivityState({ isCloudReachable: "unreachable" });
                 strategy = this.resolveStrategy(command);
                 if (strategy === "queue") {
+                    // Replays must never re-enqueue-then-delete (the command would eat
+                    // itself without executing). If no real transport is available, leave
+                    // the row untouched for a later trigger.
+                    if (opts?.forReplay) {
+                        throw new Error("ReplayDeferred: no transport available, keeping command queued");
+                    }
                     const event = await commandQueueService.enqueue(command);
                     this.broadcast(event);
                     return [event];

package/dist/sync/full-sync.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Full sync: push → pull → push.
+ * Push first so local edits (already HLC-bumped) reach server before pull
+ * overwrites them; then pull merges; final drain pushes any remainder.
+ */
+export declare function performFullSync(businessId?: string): Promise<void>;

package/dist/sync/full-sync.js

@@ -0,0 +1,72 @@
+/**
+ * Full sync: push → pull → push.
+ * Push first so local edits (already HLC-bumped) reach server before pull
+ * overwrites them; then pull merges; final drain pushes any remainder.
+ */
+import { getConnectivityState } from "../adapters/connectivity";
+import { getAuthToken } from "../adapters/auth";
+import { getActiveBusiness } from "../adapters/business";
+import { syncLogger } from "../utils/sync-logger";
+import { referenceSyncService } from "../reference/service";
+import { pullRemoteOrders, drainPending } from "./sync-jobs.service";
+let inFlight = null;
+export async function performFullSync(businessId) {
+    const bid = businessId ?? getActiveBusiness()?.id;
+    if (!bid)
+        return;
+    const s = getConnectivityState();
+    if (!s.isOnline || s.isCloudReachable === "unreachable")
+        return;
+    if (!getAuthToken())
+        return;
+    if (inFlight) {
+        try {
+            await inFlight;
+        }
+        catch { }
+        return;
+    }
+    const p = (async () => {
+        try {
+            syncLogger.info("FullSync", "Starting push→pull→push", { businessId: bid });
+            // 1. Push pending FIFO first — HLC-bumped local edits outrank stale server
+            try {
+                await drainPending(bid);
+            }
+            catch (e) {
+                syncLogger.warn("FullSync", "drainPending(pre) failed", { err: String(e) });
+            }
+            // 2. Pull remote orders (HLC-guarded) and reference (LWW merge)
+            try {
+                await pullRemoteOrders(bid);
+            }
+            catch (e) {
+                syncLogger.warn("FullSync", "pullRemoteOrders failed", { err: String(e) });
+            }
+            try {
+                await referenceSyncService.sync({ businessId: bid });
+            }
+            catch (e) {
+                syncLogger.warn("FullSync", "reference sync failed", { err: String(e) });
+            }
+            // 3. Final drain — anything newly queued or retried after pull
+            try {
+                await drainPending(bid);
+            }
+            catch (e) {
+                syncLogger.warn("FullSync", "drainPending(post) failed", { err: String(e) });
+            }
+            syncLogger.info("FullSync", "Complete", { businessId: bid });
+        }
+        catch (e) {
+            syncLogger.warn("FullSync", "Failed", { err: String(e) });
+        }
+    })();
+    inFlight = p;
+    try {
+        await p;
+    }
+    finally {
+        inFlight = null;
+    }
+}

package/dist/sync/health-probe.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Core Health Probe — periodic cloud reachability check.
+ *
+ * Probes `GET /health` using the injected HttpClient with a short timeout.
+ * On success: marks cloud reachable (triggers sync replay via connectivity
+ * subscribers). On failure: marks unreachable and schedules a retry with
+ * exponential backoff (2s → 5min cap, ±20% jitter).
+ *
+ * Started automatically by `createTeincCore()`. Host apps should not need
+ * to call this directly.
+ */
+/**
+ * Single probe attempt. Returns true if cloud is reachable.
+ */
+export declare function probeCloudHealth(): Promise<boolean>;
+/**
+ * Start the health probe. Safe to call multiple times (idempotent).
+ * Returns a stop function.
+ */
+export declare function startHealthProbe(): () => void;
+/**
+ * Stop the health probe and clean up all timers.
+ */
+export declare function stopHealthProbe(): void;