@teincfood/core 0.7.9 → 0.8.0

package/dist/sync/health-probe.js

@@ -0,0 +1,138 @@
+/**
+ * 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.
+ */
+import { getConnectivityState, setCloudReachable, subscribeConnectivity } from "../adapters/connectivity";
+import { getHttpClient } from "../adapters/http";
+import { API_BASE_URL } from "../utils/constants";
+import { syncLogger } from "../utils/sync-logger";
+import { BackoffTracker } from "./backoff";
+import { getActiveBusiness } from "../adapters/business";
+import { getAuthToken } from "../adapters/auth";
+const PROBE_URL = "/health";
+const PROBE_TIMEOUT_MS = 4000;
+const PROBE_INTERVAL_MS = 60000;
+const UNREACHABLE_COOLDOWN_MS = 15000;
+const INITIAL_DELAY_MS = 3000;
+let probeTimer = null;
+let cooldownTimer = null;
+let stopFn = null;
+const backoff = new BackoffTracker();
+/**
+ * Single probe attempt. Returns true if cloud is reachable.
+ */
+export async function probeCloudHealth() {
+    const http = (() => { try {
+        return getHttpClient();
+    }
+    catch {
+        return null;
+    } })();
+    if (!http)
+        return false;
+    const { isOnline } = getConnectivityState();
+    if (!isOnline)
+        return false;
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+        await http.get(PROBE_URL, { signal: controller.signal });
+        clearTimeout(timer);
+        backoff.reset("health");
+        const was = getConnectivityState().isCloudReachable;
+        setCloudReachable("reachable");
+        if (was !== "reachable") {
+            syncLogger.info("HealthProbe", "Cloud reachable", { previous: was });
+            // Kick off pull→merge→push without blocking probe.
+            try {
+                const bid = getActiveBusiness()?.id;
+                if (bid && getAuthToken()) {
+                    void import("./full-sync").then((m) => m.performFullSync(bid).catch(() => { }));
+                }
+            }
+            catch { }
+        }
+        return true;
+    }
+    catch {
+        // Don't mark unreachable here — the sync engine already handles that
+        // when a command times out. This probe only detects recovery.
+        // Log and backoff so we re-check later.
+        syncLogger.debug("HealthProbe", "Probe failed — will retry", {
+            previous: getConnectivityState().isCloudReachable,
+        });
+        scheduleRetry();
+        return false;
+    }
+}
+function scheduleRetry() {
+    if (cooldownTimer)
+        return;
+    const delay = Math.max(UNREACHABLE_COOLDOWN_MS, backoff.next("health"));
+    syncLogger.debug("HealthProbe", "Scheduling retry", { delay });
+    cooldownTimer = setTimeout(() => {
+        cooldownTimer = null;
+        void probeCloudHealth();
+    }, delay);
+}
+function startPeriodicProbe() {
+    if (probeTimer)
+        return;
+    probeTimer = setInterval(() => void probeCloudHealth(), PROBE_INTERVAL_MS);
+}
+function stopPeriodicProbe() {
+    if (probeTimer) {
+        clearInterval(probeTimer);
+        probeTimer = null;
+    }
+    if (cooldownTimer) {
+        clearTimeout(cooldownTimer);
+        cooldownTimer = null;
+    }
+}
+/**
+ * Start the health probe. Safe to call multiple times (idempotent).
+ * Returns a stop function.
+ */
+export function startHealthProbe() {
+    if (stopFn)
+        return stopFn;
+    syncLogger.debug("HealthProbe", "Starting", { probeUrl: `${API_BASE_URL}${PROBE_URL}` });
+    // Initial probe (deferred so host bridges can set up first)
+    cooldownTimer = setTimeout(() => {
+        cooldownTimer = null;
+        void probeCloudHealth();
+    }, INITIAL_DELAY_MS);
+    // Periodic probe
+    startPeriodicProbe();
+    // Re-probe when network regains
+    let prevOnline = getConnectivityState().isOnline;
+    const unsub = subscribeConnectivity(() => {
+        const { isOnline } = getConnectivityState();
+        if (isOnline && !prevOnline) {
+            syncLogger.debug("HealthProbe", "Network regained — probing");
+            void probeCloudHealth();
+        }
+        prevOnline = isOnline;
+    });
+    stopFn = () => {
+        stopPeriodicProbe();
+        unsub();
+        stopFn = null;
+    };
+    return stopFn;
+}
+/**
+ * Stop the health probe and clean up all timers.
+ */
+export function stopHealthProbe() {
+    if (stopFn)
+        stopFn();
+}

package/dist/sync/offline-capable.js

@@ -12,8 +12,10 @@
  */
 import { syncEngine } from "./engine";
 import { buildCommand } from "./command-builder";
+import { assertOnlineFor } from "./online-gates";
 import { syncLogger } from "../utils/sync-logger";
 import { ApiError } from "../adapters/http";
+import { getConnectivityState } from "../adapters/connectivity";
 import { CAPABILITY_BY_COMMAND } from "../reference/capabilities";
 import { openSyncDatabase } from "../db/connection";
 import { getReferenceData } from "../reference/operations";
@@ -21,6 +23,23 @@ export async function runOfflineCapableMutation(options) {
     // Per-command capability guard before even attempting direct call
     const required = CAPABILITY_BY_COMMAND[options.commandType];
     if (required) {
+        // Online-required gate first: these commands can never succeed offline —
+        // throw loud immediately instead of queuing what no transport can fulfill.
+        assertOnlineFor(options.commandType, options.payload);
+        // Local-first for engine-routed domains (menu:*): commit locally via the
+        // engine and resolve immediately. Network is sync transport only — never a
+        // mutation delay. The engine cloud path carries the same 2.5s cap and
+        // returns the backend response when online.
+        if (options.commandType.startsWith("menu:")) {
+            const command = buildCommand({
+                commandType: options.commandType,
+                businessId: options.businessId,
+                entityId: options.entityId,
+                payload: options.payload,
+            });
+            const events = await syncEngine.execute(command);
+            return events[0]?.payload;
+        }
         try {
             const db = await openSyncDatabase();
             const rec = await getReferenceData(db, options.businessId, "capabilities");
@@ -35,6 +54,12 @@ export async function runOfflineCapableMutation(options) {
         }
     }
     try {
+        // Cloud already known unreachable (or no network): skip the direct REST
+        // attempt entirely — it would only burn a timeout before falling back.
+        const cs = getConnectivityState();
+        if (!cs.isOnline || cs.isCloudReachable === "unreachable") {
+            throw new Error("offline-capable: cloud known unreachable, engine route");
+        }
         return await options.run();
     }
     catch (error) {

package/dist/sync/online-gates.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Online-required allowlist — single source for what can NEVER work offline.
+ *
+ * Everything else is offline-first (SQLite read, local commit, engine sync).
+ * These commands throw immediately when the cloud is unreachable: queuing
+ * them would be dishonest because no transport (LAN or outbox replay) can
+ * ever fulfill them without the backend.
+ */
+/** Command types that require the cloud, unconditionally. */
+export declare const ONLINE_REQUIRED: Record<string, string>;
+export declare function isOnlineCapable(): boolean;
+/**
+ * Throw when a command cannot proceed offline. Handles payload-dependent
+ * cases: order:create with delivery type or prepaid/mobile-money payment,
+ * and delivery/order transitions the domain already gates.
+ */
+export declare function assertOnlineFor(commandType: string, payload?: Record<string, unknown>): void;

package/dist/sync/online-gates.js

@@ -0,0 +1,55 @@
+/**
+ * Online-required allowlist — single source for what can NEVER work offline.
+ *
+ * Everything else is offline-first (SQLite read, local commit, engine sync).
+ * These commands throw immediately when the cloud is unreachable: queuing
+ * them would be dishonest because no transport (LAN or outbox replay) can
+ * ever fulfill them without the backend.
+ */
+import { getConnectivityState } from "../adapters/connectivity";
+/** Command types that require the cloud, unconditionally. */
+export const ONLINE_REQUIRED = {
+    "order:assign_rider": "Assign rider requires online",
+    "order:confirm_handover": "Handover confirmation requires online",
+    "chat:send": "Chat requires online",
+    "notification:register": "Notifications require online",
+    "member:invite": "Member invites require online",
+    "member:manage": "Member management requires online",
+    "fleet:manage": "Fleet changes require online",
+    "settings:manage": "Settings changes require online",
+    "kyc:submit": "KYC submission requires online",
+    "wallet:withdraw": "Withdrawals require online",
+    "wallet:payout": "Payouts require online",
+    "payment:charge_online": "Online payment requires online",
+    "device:lease": "Device lease requires online (first lease only)",
+};
+export function isOnlineCapable() {
+    const s = getConnectivityState();
+    return s.isOnline && s.isCloudReachable !== "unreachable";
+}
+/**
+ * Throw when a command cannot proceed offline. Handles payload-dependent
+ * cases: order:create with delivery type or prepaid/mobile-money payment,
+ * and delivery/order transitions the domain already gates.
+ */
+export function assertOnlineFor(commandType, payload) {
+    const fixed = ONLINE_REQUIRED[commandType];
+    if (fixed) {
+        if (!isOnlineCapable())
+            throw new Error(fixed);
+        return;
+    }
+    if (commandType === "order:create" && payload) {
+        const orderType = payload.order_type;
+        if (orderType === "delivery" || payload.delivery_params) {
+            if (!isOnlineCapable())
+                throw new Error("Delivery orders require online");
+            return;
+        }
+        const method = payload.pos_payment_method;
+        if (typeof method === "string" && method !== "cash") {
+            if (!isOnlineCapable())
+                throw new Error("Online payment requires online — use cash while offline");
+        }
+    }
+}

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

@@ -5,15 +5,15 @@
  * CCC = callout 001-999 global monotonic per device, wraps to 001 (new RRR on wrap)
  * Example: "10-123-001"
  */
-export declare function peekCallout(): number;
-export declare function generateOrderNumber(deviceNumber: string): {
+export declare function peekCallout(businessId?: string | null): number;
+export declare function generateOrderNumber(deviceNumber: string, businessId?: string | null): {
     orderNumber: string;
     callout: number;
     random: number;
 };
 export declare function generateLocalOrderNumber(): string;
 export declare function generateOrderNumberForBusiness(businessId: string): string;
-export declare function generateLocalCalloutNumber(): number;
+export declare function generateLocalCalloutNumber(businessId?: string | null): number;
 export declare function isLocalOrderNumber(orderNumber: string): boolean;
 export declare function isOfflineOrderNumber(orderNumber: string): boolean;
 export declare function parseOrderNumber(orderNumber: string): {
@@ -21,4 +21,4 @@ export declare function parseOrderNumber(orderNumber: string): {
     random: string;
     callout: string;
 } | null;
-export declare function resetCalloutForTests(): void;
+export declare function resetCalloutForTests(businessId?: string | null): void;

package/dist/sync/order-number.js

@@ -16,23 +16,37 @@ function cryptoRandom100to999() {
     }
     return 100 + Math.floor(Math.random() * 900);
 }
-function getNextCallout() {
-    const stored = getItem(CALLOUT_SEQ_KEY);
+function calloutKeyForBusiness(businessId) {
+    return businessId ? `${CALLOUT_SEQ_KEY}:${businessId}` : CALLOUT_SEQ_KEY;
+}
+function getNextCallout(businessId) {
+    const key = calloutKeyForBusiness(businessId);
+    const stored = getItem(key);
     let next = (stored ?? 0) + 1;
     if (next > 999)
         next = 1;
-    setItem(CALLOUT_SEQ_KEY, next);
+    setItem(key, next);
+    // migrate legacy global once: keep global in sync for backward compat
+    if (businessId) {
+        const legacy = getItem(CALLOUT_SEQ_KEY) ?? 0;
+        if (legacy < next)
+            setItem(CALLOUT_SEQ_KEY, next);
+    }
     return next;
 }
-export function peekCallout() {
-    const stored = getItem(CALLOUT_SEQ_KEY);
-    return stored ?? 0;
+export function peekCallout(businessId) {
+    const key = calloutKeyForBusiness(businessId);
+    const v = getItem(key);
+    if (v != null)
+        return v;
+    const legacy = getItem(CALLOUT_SEQ_KEY);
+    return legacy ?? 0;
 }
-export function generateOrderNumber(deviceNumber) {
+export function generateOrderNumber(deviceNumber, businessId) {
     if (!/^(0[1-9]|[1-9][0-9])$/.test(deviceNumber)) {
         throw new Error(`Invalid deviceNumber ${deviceNumber} — must be 01-99`);
     }
-    const callout = getNextCallout();
+    const callout = getNextCallout(businessId);
     let random = cryptoRandom100to999();
     // On wrap to 001, ensure new random (already new per order, but keep hook)
     if (callout === 1) {
@@ -53,11 +67,11 @@ export function generateOrderNumberForBusiness(businessId) {
     if (!v || !/^(0[1-9]|[1-9][0-9])$/.test(v)) {
         throw new Error(`No device lease for business ${businessId} — call ensureLease(businessId) first (online-only until leased)`);
     }
-    return generateOrderNumber(v).orderNumber;
+    return generateOrderNumber(v, businessId).orderNumber;
 }
-export function generateLocalCalloutNumber() {
-    // kept for SellerOrder.callout_number compatibility — returns CCC
-    const next = peekCallout() + 1;
+export function generateLocalCalloutNumber(businessId) {
+    // kept for SellerOrder.callout_number compatibility — returns next CCC
+    const next = peekCallout(businessId) + 1;
     return next > 999 ? 1 : next;
 }
 // New canonical check — unified for DD-RRR-CCC
@@ -74,6 +88,12 @@ export function parseOrderNumber(orderNumber) {
     return { deviceNumber: m[1], random: m[2], callout: m[3] };
 }
 // Test helpers
-export function resetCalloutForTests() {
+export function resetCalloutForTests(businessId) {
+    if (businessId) {
+        setItem(calloutKeyForBusiness(businessId), 0);
+        return;
+    }
     setItem(CALLOUT_SEQ_KEY, 0);
+    // also clear per-business keys that tests may have touched
+    // caller should pass businessId if they used business-scoped sequences
 }

package/dist/sync/order-snapshots.service.js

@@ -74,7 +74,19 @@ class OrderSnapshotsService {
     }
     async applyOrderStatusToReadModelInternal(db, orderId, toStatus, event) {
         try {
-            const lists = await getEntitySnapshotsByType(db, "seller_orders");
+            const payload = event.payload;
+            const businessId = payload?.business_id ?? payload?.businessId ?? null;
+            // Dual-write: keep canonical orders table in sync so POS/KDS reads converge instantly.
+            if (businessId) {
+                try {
+                    const { updateOrderStatus } = await import("../db/operations");
+                    await updateOrderStatus(db, businessId, orderId, toStatus, event.timestamp);
+                }
+                catch { }
+            }
+            const lists = businessId
+                ? await getEntitySnapshotsByType(db, "seller_orders", businessId)
+                : await getEntitySnapshotsByType(db, "seller_orders");
             for (const list of lists) {
                 const data = list.payload.data ?? [];
                 const idx = data.findIndex((o) => o.id === orderId);
@@ -106,7 +118,10 @@ class OrderSnapshotsService {
         try {
             const db = await openSyncDatabase();
             await insertEvent(db, { event, origin });
-            const lists = await getEntitySnapshotsByType(db, "seller_orders");
+            const businessId = payload?.business_id ?? payload?.businessId ?? null;
+            const lists = businessId
+                ? await getEntitySnapshotsByType(db, "seller_orders", businessId)
+                : await getEntitySnapshotsByType(db, "seller_orders");
             for (const list of lists) {
                 const data = list.payload.data ?? [];
                 const idx = data.findIndex((o) => o.id === orderId || o.order_number === payload?.order_number);
@@ -173,7 +188,7 @@ class OrderSnapshotsService {
     async getSellerList(businessId, scope) {
         try {
             const db = await openSyncDatabase();
-            const snap = await getEntitySnapshot(db, "seller_orders", scope);
+            const snap = await getEntitySnapshot(db, "seller_orders", scope, businessId);
             if (!snap || snap.business_id !== businessId)
                 return null;
             return snap.payload.data ?? null;

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

@@ -15,11 +15,29 @@
  * order's `order_number`.
  */
 import type { DomainEvent } from "./types";
+import type { SellerOrder } from "../types/api/seller.api";
 /**
  * Register a callback used to invalidate TanStack Query caches when a pending
  * order is reconciled. Returns an unregister function.
  */
 export declare function registerPendingOrdersInvalidator(fn: () => void): () => void;
+/**
+ * Fire the registered query invalidator (lists refetch from SQLite).
+ * Used after LAN-applied writes (order:sync) that bypass the engine event
+ * pipeline, so peers' UIs converge without waiting for a cloud echo.
+ */
+export declare function notifyPendingOrdersChanged(): void;
+/**
+ * Merge optimistic (queued, unconfirmed) state into a page of listed orders.
+ * Called by list queryFns (page 1 only) so offline work is visible:
+ *  1. Pending creations (order.create_queued, local or LAN) missing from the
+ *     SQLite page are prepended — deduped by id/order_number.
+ *  2. Queued transitions only patch the snapshot read model, never the
+ *     orders table — overlay snapshot statuses onto base rows so the list
+ *     reflects the queued status immediately (converges on replay).
+ * Reactivity comes from the invalidator: every apply path above refetches.
+ */
+export declare function mergePendingIntoList(base: SellerOrder[], businessId: string, page: number): Promise<SellerOrder[]>;
 /**
  * Load persisted unsynced order:create_queued events into the store.
  * Idempotent; safe to call after app restart while still offline.

package/dist/sync/pending-orders.service.js

@@ -15,7 +15,7 @@
  * order's `order_number`.
  */
 import { openSyncDatabase } from "../db/connection";
-import { insertEvent, getUnsyncedEvents, markEventsSynced, } from "../db/operations";
+import { insertEvent, getUnsyncedEvents, markEventsSynced, getEntitySnapshotsByType, } from "../db/operations";
 import { usePendingOrdersStore } from "../adapters/pending-orders";
 import { orderSnapshotsService } from "./order-snapshots.service";
 import { syncLogger } from "../utils/sync-logger";
@@ -49,6 +49,72 @@ export function registerPendingOrdersInvalidator(fn) {
             invalidator = null;
     };
 }
+/**
+ * Fire the registered query invalidator (lists refetch from SQLite).
+ * Used after LAN-applied writes (order:sync) that bypass the engine event
+ * pipeline, so peers' UIs converge without waiting for a cloud echo.
+ */
+export function notifyPendingOrdersChanged() {
+    try {
+        invalidator?.();
+    }
+    catch { }
+}
+/**
+ * Merge optimistic (queued, unconfirmed) state into a page of listed orders.
+ * Called by list queryFns (page 1 only) so offline work is visible:
+ *  1. Pending creations (order.create_queued, local or LAN) missing from the
+ *     SQLite page are prepended — deduped by id/order_number.
+ *  2. Queued transitions only patch the snapshot read model, never the
+ *     orders table — overlay snapshot statuses onto base rows so the list
+ *     reflects the queued status immediately (converges on replay).
+ * Reactivity comes from the invalidator: every apply path above refetches.
+ */
+export async function mergePendingIntoList(base, businessId, page) {
+    if (page !== 1)
+        return base;
+    let merged = base;
+    try {
+        const pending = usePendingOrdersStore.getState().orders;
+        if (pending.length) {
+            const seen = new Set(merged.map((o) => String(o.id ?? o.order_number)));
+            const fresh = pending.filter((p) => !seen.has(String(p.id ?? p.order_number)));
+            if (fresh.length)
+                merged = [...fresh, ...merged];
+        }
+    }
+    catch { }
+    try {
+        const db = await openSyncDatabase();
+        const snaps = await getEntitySnapshotsByType(db, "seller_orders", businessId);
+        if (!snaps.length)
+            return merged;
+        const statusById = new Map();
+        for (const s of snaps) {
+            const arr = s.payload?.data ?? [];
+            for (const o of arr) {
+                if (o?.id && o.status)
+                    statusById.set(String(o.id), String(o.status));
+            }
+        }
+        if (!statusById.size)
+            return merged;
+        let patched = false;
+        merged = merged.map((o) => {
+            const want = statusById.get(String(o.id));
+            if (want && want !== o.status) {
+                patched = true;
+                return { ...o, status: want };
+            }
+            return o;
+        });
+        if (patched) {
+            syncLogger.debug("PendingOrders", "overlaid queued statuses onto list", { businessId, count: merged.length });
+        }
+    }
+    catch { }
+    return merged;
+}
 /**
  * Load persisted unsynced order:create_queued events into the store.
  * Idempotent; safe to call after app restart while still offline.

package/dist/sync/reconciliation/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Global realtime reconciliation — RECONCILE_DEBOUNCE_MS 400 Set coalesce (§24).
+ * Canonical in src/sync/use-sync-reconciliation.
+ */
+export * from "../use-sync-reconciliation";

package/dist/sync/reconciliation/index.js

@@ -0,0 +1,5 @@
+/**
+ * Global realtime reconciliation — RECONCILE_DEBOUNCE_MS 400 Set coalesce (§24).
+ * Canonical in src/sync/use-sync-reconciliation.
+ */
+export * from "../use-sync-reconciliation";

package/dist/sync/snapshots/entity.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Entity snapshots — local read model (§9 SQLite Model).
+ * Canonical in src/db/operations + src/sync/order-snapshots.service.
+ */
+export { upsertEntitySnapshot, getEntitySnapshot, getEntitySnapshotsByType, pruneEntitySnapshots } from "../../db/operations";
+export { orderSnapshotsService } from "../order-snapshots.service";

package/dist/sync/snapshots/entity.js

@@ -0,0 +1,6 @@
+/**
+ * Entity snapshots — local read model (§9 SQLite Model).
+ * Canonical in src/db/operations + src/sync/order-snapshots.service.
+ */
+export { upsertEntitySnapshot, getEntitySnapshot, getEntitySnapshotsByType, pruneEntitySnapshots } from "../../db/operations";
+export { orderSnapshotsService } from "../order-snapshots.service";

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

@@ -0,0 +1,18 @@
+/**
+ * Sync Jobs FIFO — near real-time drain after local commit.
+ * Tries PHX business:{id} push first, then REST, queues on fail.
+ * 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>;
+export declare function drainPending(businessId: string): Promise<void>;
+export declare function setupSyncJobsDrain(): void;
+export declare function getSyncJobsPendingCount(businessId: string): Promise<number>;
+export declare function debugDumpSyncJobs(businessId: string): Promise<Array<{
+    id: string;
+    command_type: string;
+    status: string;
+    created_at: string;
+    attempts: number;
+    last_error: string | null;
+}>>;