@teincfood/core 0.10.25 → 0.10.27

package/dist/catalog/hooks.d.ts

@@ -17,19 +17,20 @@ export declare function useMenuItemsQuery(filters?: {
     data: unknown[] | undefined;
 };
 export declare function useMenuCategoriesQuery(): ReturnType<typeof useQuery>;
-export declare function useCreateMenuItemMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, Record<string, unknown>, unknown>;
-export declare function useUpdateMenuItemMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, {
+export declare function useCreateMenuItemMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, Record<string, unknown>, unknown>;
+export declare function useUpdateMenuItemMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, {
     id: string;
     payload: Record<string, unknown>;
 }, unknown>;
-export declare function useDeleteMenuItemMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, string, unknown>;
-export declare function useToggleItemAvailabilityMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, {
+export declare function useDeleteMenuItemMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, string, unknown>;
+export declare function useToggleItemAvailabilityMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, {
     id: string;
     available: boolean;
+    cacheRecord?: unknown;
 }, unknown>;
-export declare function useCreateMenuCategoryMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, Record<string, unknown>, unknown>;
-export declare function useUpdateMenuCategoryMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, {
+export declare function useCreateMenuCategoryMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, Record<string, unknown>, unknown>;
+export declare function useUpdateMenuCategoryMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, {
     id: string;
     payload: Record<string, unknown>;
 }, unknown>;
-export declare function useDeleteMenuCategoryMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, string, unknown>;
+export declare function useDeleteMenuCategoryMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, string, unknown>;

package/dist/catalog/hooks.js

@@ -11,8 +11,7 @@ import { menuService } from "../adapters/services";
 import { getReferenceData } from "../reference/operations";
 import { openSyncDatabase } from "../db/connection";
 import { referenceSyncService } from "../reference/service";
-import { emitReferenceChanged } from "../reference/events";
-import { runOfflineCapableMutation } from "../sync/offline-capable";
+import { commitMenuMutationLocal } from "../sync/offline-capable";
 import { useIsEffectivelyOnline } from "../hooks/use-infinite-list";
 export const CATALOG_KEYS = {
     all: ["menu"],
@@ -134,21 +133,24 @@ export function useMenuCategoriesQuery() {
         error: hasCache ? null : networkQuery.error,
     };
 }
-// Mutations — offline-capable
+// Mutations — local-first.
+//
+// The only work on the mutation path is the local SQLite commit. Reference
+// fan-out and cloud/LAN replay are scheduled by commitMenuMutationLocal AFTER
+// the outbox row exists, so a slow or absent network can never delay a save.
+// Invalidating the cached query key makes the committed row render immediately.
 export function useCreateMenuItemMutation() {
     const businessId = useBusinessId();
     const qc = useQueryClient();
     return useMutation({
-        mutationFn: (payload) => {
-            // cacheRecord is local-cache only — never on the wire.
-            const { cacheRecord: _omit, ...wire } = payload;
-            void _omit;
-            return runOfflineCapableMutation({ run: () => menuService.createMenuItem(wire), commandType: "menu:create_item", businessId: businessId, entityId: payload.id, payload });
-        },
+        mutationFn: (payload) => commitMenuMutationLocal({
+            commandType: "menu:create_item",
+            businessId: businessId,
+            entityId: payload.id,
+            payload,
+        }),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:items"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
         },
     });
 }
@@ -156,15 +158,14 @@ export function useUpdateMenuItemMutation() {
     const businessId = useBusinessId();
     const qc = useQueryClient();
     return useMutation({
-        mutationFn: ({ id, payload }) => {
-            const { cacheRecord: _omit, ...wire } = payload;
-            void _omit;
-            return runOfflineCapableMutation({ run: () => menuService.updateMenuItem(id, wire), commandType: "menu:update_item", businessId: businessId, entityId: id, payload });
-        },
+        mutationFn: ({ id, payload }) => commitMenuMutationLocal({
+            commandType: "menu:update_item",
+            businessId: businessId,
+            entityId: id,
+            payload,
+        }),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:items"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
         },
     });
 }
@@ -172,11 +173,14 @@ export function useDeleteMenuItemMutation() {
     const businessId = useBusinessId();
     const qc = useQueryClient();
     return useMutation({
-        mutationFn: (id) => runOfflineCapableMutation({ run: () => menuService.deleteMenuItem(id), commandType: "menu:delete_item", businessId: businessId, entityId: id, payload: { id } }),
+        mutationFn: (id) => commitMenuMutationLocal({
+            commandType: "menu:delete_item",
+            businessId: businessId,
+            entityId: id,
+            payload: { id },
+        }),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:items"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
         },
     });
 }
@@ -184,13 +188,14 @@ export function useToggleItemAvailabilityMutation() {
     const businessId = useBusinessId();
     const qc = useQueryClient();
     return useMutation({
-        // Availability is an update_item with an availability patch — same engine
-        // route (cloud → LAN → queue), same cache convergence.
-        mutationFn: ({ id, available }) => runOfflineCapableMutation({ run: () => menuService.updateMenuItem(id, { available }), commandType: "menu:update_item", businessId: businessId, entityId: id, payload: { id, available } }),
+        mutationFn: ({ id, available, cacheRecord }) => commitMenuMutationLocal({
+            commandType: "menu:update_item",
+            businessId: businessId,
+            entityId: id,
+            payload: cacheRecord ? { id, available, cacheRecord } : { id, available },
+        }),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:items"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
         },
     });
 }
@@ -198,15 +203,14 @@ export function useCreateMenuCategoryMutation() {
     const businessId = useBusinessId();
     const qc = useQueryClient();
     return useMutation({
-        mutationFn: (payload) => {
-            const { cacheRecord: _omit, ...wire } = payload;
-            void _omit;
-            return runOfflineCapableMutation({ run: () => menuService.createCategory(businessId, wire), commandType: "menu:create_category", businessId: businessId, entityId: payload.id, payload });
-        },
+        mutationFn: (payload) => commitMenuMutationLocal({
+            commandType: "menu:create_category",
+            businessId: businessId,
+            entityId: payload.id,
+            payload,
+        }),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.categories(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:categories"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.categories(businessId) });
         },
     });
 }
@@ -214,15 +218,14 @@ export function useUpdateMenuCategoryMutation() {
     const businessId = useBusinessId();
     const qc = useQueryClient();
     return useMutation({
-        mutationFn: ({ id, payload }) => {
-            const { cacheRecord: _omit, ...wire } = payload;
-            void _omit;
-            return runOfflineCapableMutation({ run: () => menuService.updateCategory(id, wire), commandType: "menu:update_category", businessId: businessId, entityId: id, payload: { ...payload, id } });
-        },
+        mutationFn: ({ id, payload }) => commitMenuMutationLocal({
+            commandType: "menu:update_category",
+            businessId: businessId,
+            entityId: id,
+            payload: { ...payload, id },
+        }),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.categories(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:categories"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.categories(businessId) });
         },
     });
 }
@@ -230,11 +233,14 @@ export function useDeleteMenuCategoryMutation() {
     const businessId = useBusinessId();
     const qc = useQueryClient();
     return useMutation({
-        mutationFn: (id) => runOfflineCapableMutation({ run: () => menuService.deleteCategory(id), commandType: "menu:delete_category", businessId: businessId, entityId: id, payload: { id } }),
+        mutationFn: (id) => commitMenuMutationLocal({
+            commandType: "menu:delete_category",
+            businessId: businessId,
+            entityId: id,
+            payload: { id },
+        }),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.categories(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:categories"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.categories(businessId) });
         },
     });
 }

package/dist/index.d.ts

@@ -73,8 +73,8 @@ export { localNodeTransport } from "./sync/transport-local-node";
 export * from "./sync/transport-local-node";
 export * from "./sync/order-snapshots.service";
 export { hydratePendingOrders, applyPendingOrderEvent, applyOrderStateChangeEvent } from "./sync/pending-orders.service";
-export { runOfflineCapableMutation } from "./sync/offline-capable";
-export type { OfflineCapableOptions } from "./sync/offline-capable";
+export { commitMenuMutationLocal, runOfflineCapableMutation } from "./sync/offline-capable";
+export type { LocalMenuMutationOptions, OfflineCapableOptions } from "./sync/offline-capable";
 export { orderRepository } from "./repositories/order.repository";
 export type { CreateOrderInput, AssignRiderInput, OrderActionInput } from "./repositories/order.repository";
 export { posRepository } from "./repositories/pos.repository";

package/dist/index.js

@@ -75,7 +75,7 @@ export { localNodeTransport } from "./sync/transport-local-node";
 export * from "./sync/transport-local-node";
 export * from "./sync/order-snapshots.service";
 export { hydratePendingOrders, applyPendingOrderEvent, applyOrderStateChangeEvent } from "./sync/pending-orders.service";
-export { runOfflineCapableMutation } from "./sync/offline-capable";
+export { commitMenuMutationLocal, runOfflineCapableMutation } from "./sync/offline-capable";
 // ── Repositories ──
 export { orderRepository } from "./repositories/order.repository";
 export { posRepository } from "./repositories/pos.repository";

package/dist/sync/offline-capable.d.ts

@@ -10,6 +10,7 @@
  *
  * Keeps the online path and its result shape unchanged.
  */
+import type { DomainEvent } from "./types";
 export interface OfflineCapableOptions<TService, TCommandPayload> {
     /** Direct REST call — used online. */
     run: () => Promise<TService>;
@@ -19,4 +20,24 @@ export interface OfflineCapableOptions<TService, TCommandPayload> {
     entityId?: string;
     payload: TCommandPayload;
 }
+export interface LocalMenuMutationOptions<TCommandPayload> {
+    /** Must be a `menu:*` command. */
+    commandType: string;
+    businessId: string;
+    entityId?: string;
+    payload: TCommandPayload;
+}
+/**
+ * The ONLY menu write path.
+ *
+ * Local SQLite is the source of truth: capability/entitlement checks read the
+ * cached proof, the menu row is applied to the reference cache, and the
+ * command is inserted into the durable outbox. All of that completes before
+ * this promise resolves. No HTTP, connectivity probe, image upload, reference
+ * pull, LAN call, or replay is allowed here.
+ *
+ * Consumers must treat the returned event as the committed local state and
+ * close the form immediately. Sync is a separate background worker.
+ */
+export declare function commitMenuMutationLocal<TCommandPayload>(options: LocalMenuMutationOptions<TCommandPayload>): Promise<DomainEvent>;
 export declare function runOfflineCapableMutation<TService, TCommandPayload>(options: OfflineCapableOptions<TService, TCommandPayload>): Promise<TService>;

package/dist/sync/offline-capable.js

@@ -24,61 +24,121 @@ import { applyMenuCommandLocal } from "../reference/menu-apply";
 import { emitReferenceChanged } from "../reference/events";
 import { assertEntitledForCommand } from "../reference/entitlement-guard";
 import { isOnlineCapable } from "./online-gates";
-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:*): persist to SQLite and the
-        // durable outbox immediately, update the local reference cache, and let
-        // replay upload to the cloud/LAN in the background. A slow or absent
-        // network must never hold the form open.
-        if (options.commandType.startsWith("menu:")) {
-            // Preserve the entitlement gate that the engine normally applies before
-            // queueing: local-first must not weaken subscription enforcement.
-            await assertEntitledForCommand(options.businessId, options.commandType);
-            const command = buildCommand({
-                commandType: options.commandType,
-                businessId: options.businessId,
-                entityId: options.entityId,
-                payload: options.payload,
-            });
+/**
+ * Enforce the cached RBAC capabilities downloaded from the backend.
+ *
+ * Fail-open only when no capabilities record exists yet (first boot); once a
+ * record is present, an unknown capability is a real denial and must never
+ * reach the local cache or the outbox.
+ */
+async function assertCachedCapability(businessId, required) {
+    try {
+        const db = await openSyncDatabase();
+        const rec = await getReferenceData(db, businessId, "capabilities");
+        const caps = rec?.payload?.data
+            ?.capabilities ?? [];
+        if (rec && caps.length > 0 && !caps.includes(required)) {
+            throw new ApiError(`Missing capability: ${required}`, 403, "FORBIDDEN");
+        }
+    }
+    catch (e) {
+        if (e instanceof ApiError && e.status === 403)
+            throw e;
+    }
+}
+/**
+ * Publish fan-out only after the local transaction has committed.
+ *
+ * This is deliberately scheduled off the mutation's promise: reference sync
+ * and replay are downstream of SQLite, never a prerequisite for it. If either
+ * fails, the local row and outbox stay intact for the next retry.
+ */
+function scheduleMenuPostCommit(businessId, keys) {
+    setTimeout(() => {
+        if (keys.length > 0) {
             try {
-                const { keys } = await applyMenuCommandLocal(options.businessId, command);
-                if (keys.length)
-                    emitReferenceChanged(options.businessId, keys);
+                emitReferenceChanged(businessId, keys);
             }
             catch (error) {
-                syncLogger.debug("OfflineCapable", "menu local apply failed", {
+                syncLogger.debug("OfflineCapable", "menu reference fan-out failed", {
                     error: String(error),
                 });
             }
-            const event = await commandQueueService.enqueue(command);
-            if (isOnlineCapable()) {
-                // Background only: save must return now.
-                void syncEngine.replayQueuedCommands().catch((error) => {
-                    syncLogger.debug("OfflineCapable", "menu background replay failed", {
-                        error: String(error),
-                    });
-                });
-            }
-            return event.payload;
         }
-        try {
-            const db = await openSyncDatabase();
-            const rec = await getReferenceData(db, options.businessId, "capabilities");
-            const caps = rec?.payload?.data?.capabilities ?? [];
-            if (rec && caps.length > 0 && !caps.includes(required)) {
-                throw new ApiError(`Missing capability: ${required}`, 403, "FORBIDDEN");
-            }
-        }
-        catch (e) {
-            if (e instanceof ApiError && e.status === 403)
-                throw e;
+        if (isOnlineCapable()) {
+            void syncEngine.replayQueuedCommands().catch((error) => {
+                syncLogger.debug("OfflineCapable", "menu background replay failed", {
+                    error: String(error),
+                });
+            });
         }
+    }, 0);
+}
+/**
+ * The ONLY menu write path.
+ *
+ * Local SQLite is the source of truth: capability/entitlement checks read the
+ * cached proof, the menu row is applied to the reference cache, and the
+ * command is inserted into the durable outbox. All of that completes before
+ * this promise resolves. No HTTP, connectivity probe, image upload, reference
+ * pull, LAN call, or replay is allowed here.
+ *
+ * Consumers must treat the returned event as the committed local state and
+ * close the form immediately. Sync is a separate background worker.
+ */
+export async function commitMenuMutationLocal(options) {
+    if (!options.commandType.startsWith("menu:")) {
+        throw new Error(`commitMenuMutationLocal only accepts menu:* commands, got ${options.commandType}`);
+    }
+    // Cached permission proof — local reads only. The backend remains the final
+    // authority when the queued command replays.
+    const required = CAPABILITY_BY_COMMAND[options.commandType];
+    if (required)
+        await assertCachedCapability(options.businessId, required);
+    await assertEntitledForCommand(options.businessId, options.commandType);
+    const command = buildCommand({
+        commandType: options.commandType,
+        businessId: options.businessId,
+        entityId: options.entityId,
+        payload: options.payload,
+    });
+    // 1) local read model, 2) durable outbox. Both are local writes.
+    let keys = [];
+    try {
+        const applied = await applyMenuCommandLocal(options.businessId, command);
+        keys = applied.keys;
+    }
+    catch (error) {
+        // The outbox row is still authoritative and will re-apply on replay.
+        syncLogger.debug("OfflineCapable", "menu local apply failed", {
+            error: String(error),
+        });
+    }
+    const event = await commandQueueService.enqueue(command);
+    // 3) only now may the rest of the system hear about it.
+    scheduleMenuPostCommit(options.businessId, keys);
+    return event;
+}
+export async function runOfflineCapableMutation(options) {
+    // Menu writes have a dedicated local-first API. Keep this branch for legacy
+    // callers (e.g. image upload follow-ups) but route it through the same
+    // commit-only implementation.
+    if (options.commandType.startsWith("menu:")) {
+        const event = await commitMenuMutationLocal({
+            commandType: options.commandType,
+            businessId: options.businessId,
+            entityId: options.entityId,
+            payload: options.payload,
+        });
+        return event.payload;
     }
+    // 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);
+    // Per-command capability guard before touching local state or the network.
+    const required = CAPABILITY_BY_COMMAND[options.commandType];
+    if (required)
+        await assertCachedCapability(options.businessId, required);
     try {
         // Cloud already known unreachable (or no network): skip the direct REST
         // attempt entirely — it would only burn a timeout before falling back.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teincfood/core",
-  "version": "0.10.25",
+  "version": "0.10.27",
   "description": "TeincFood shared offline-first core — types, sync engine, local DB, reference data, and repositories for mobile + desktop",
   "type": "module",
   "main": "dist/index.js",