@teincfood/core 0.7.8 → 0.8.0

package/dist/reference/hooks.js

@@ -0,0 +1,124 @@
+/**
+ * Reference-data React hooks — single source for both apps.
+ * Sync hooks use core connectivity/business adapters; cache reads are pure
+ * SQLite (never network). Image-query invalidation uses the shared
+ * ["cachedImage"] prefix both apps use.
+ */
+import { useEffect, useCallback } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useSyncExternalStore } from "react";
+import { getActiveBusiness, subscribeBusiness } from "../adapters/business";
+import { getConnectivityState, subscribeConnectivity } from "../adapters/connectivity";
+import { openSyncDatabase } from "../db/connection";
+import { referenceSyncService } from "./service";
+import { getReferenceData } from "./operations";
+export const REFERENCE_KEYS = {
+    all: ["reference"],
+    sync: ["reference", "sync"],
+    data: (key) => ["reference", "data", key],
+};
+function useActiveBusinessId() {
+    const id = useSyncExternalStore(subscribeBusiness, () => getActiveBusiness()?.id ?? null, () => null);
+    return id ?? undefined;
+}
+function useConnectivitySnapshot() {
+    return useSyncExternalStore(subscribeConnectivity, getConnectivityState, getConnectivityState);
+}
+/**
+ * Trigger reference data synchronization when the active business changes.
+ * Does not return data; fires a background sync. Set `enabled` to false to
+ * disable automatic sync.
+ */
+export function useReferenceDataSync(businessId, options = {}) {
+    const { enabled = true, ...syncOptions } = options;
+    useEffect(() => {
+        if (!enabled || !businessId)
+            return;
+        let cancelled = false;
+        referenceSyncService
+            .sync({ businessId, ...syncOptions })
+            .then((result) => {
+            if (cancelled)
+                return;
+            if (result.failed.length > 0) {
+                try {
+                    console.debug("[ReferenceSync] failed keys (non-fatal):", result.failed);
+                }
+                catch { }
+            }
+        })
+            .catch(() => {
+            if (cancelled)
+                return;
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [businessId, enabled, JSON.stringify(syncOptions)]);
+}
+/** Manually trigger reference data sync. */
+export function useSyncReferenceData() {
+    return useCallback(async (options) => {
+        return referenceSyncService.sync(options);
+    }, []);
+}
+/**
+ * App-level reference sync: downloads every reference-backed dataset into
+ * the SQLite cache so the business operates fully offline. Call once from
+ * the app root/layouts. Strict reachable gate — `unknown` (cold start)
+ * must not fire sync, otherwise airplane launch hangs on versions fetch.
+ */
+export function useBusinessReferenceDataSync() {
+    const businessId = useActiveBusinessId();
+    const connectivity = useConnectivitySnapshot();
+    const queryClient = useQueryClient();
+    const isOnline = connectivity.isOnline;
+    const isCloudReachable = connectivity.isCloudReachable;
+    useEffect(() => {
+        if (!businessId || !isOnline || isCloudReachable !== "reachable")
+            return;
+        let cancelled = false;
+        referenceSyncService
+            .sync({ businessId })
+            .then((result) => {
+            if (cancelled)
+                return;
+            try {
+                void queryClient.invalidateQueries({ queryKey: ["cachedImage"] });
+            }
+            catch { }
+            if (result.failed.length > 0) {
+                try {
+                    console.debug("[ReferenceSync] failed keys (non-fatal):", result.failed);
+                }
+                catch { }
+            }
+        })
+            .catch(() => {
+            if (cancelled)
+                return;
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [businessId, isOnline, isCloudReachable, queryClient]);
+}
+/**
+ * Read a reference data record from the local SQLite cache for the active
+ * business. Never hits the network.
+ */
+export function useReferenceData(key) {
+    const businessId = useActiveBusinessId();
+    return useQuery({
+        queryKey: [...REFERENCE_KEYS.data(key), businessId],
+        queryFn: async () => {
+            if (!businessId)
+                return null;
+            const db = await openSyncDatabase();
+            return getReferenceData(db, businessId, key);
+        },
+        staleTime: Infinity,
+        enabled: !!businessId,
+    });
+}

package/dist/reference/menu-apply.d.ts

@@ -0,0 +1,29 @@
+import type { ReferenceDataKey } from "./types";
+import type { Command } from "../sync/types";
+export declare const MENU_ITEM_KEY: ReferenceDataKey;
+export declare const MENU_CATEGORY_KEY: ReferenceDataKey;
+/**
+ * Apply a menu:* command to the local reference cache. Returns affected keys
+ * (for reference_data.changed fan-out) and whether anything was written.
+ * Idempotent by entity id: re-applying the same command converges.
+ */
+export declare function applyMenuCommandLocal(businessId: string, command: Pick<Command, "command_type" | "entity_id" | "command_id" | "payload">): Promise<{
+    keys: ReferenceDataKey[];
+    applied: boolean;
+}>;
+/**
+ * Revert an optimistic menu write after a definitive backend rejection:
+ * restores the stashed prior record, or deletes the row for creates.
+ * Peers converge via reference_fetch/pull on the next sync.
+ */
+export declare function revertMenuCommand(businessId: string, commandType: string, entityId: string): Promise<boolean>;
+/** Keys whose cache a menu command affects (for fan-out without applying). */
+export declare function menuCommandKeys(commandType: string): ReferenceDataKey[];
+/**
+ * One-time janitor: remove cached menu rows that are not backend-shaped
+ * MenuItems (written by older builds that cached raw wire payloads). This is
+ * explicit removal of invalid data — never translation. The outbox remains
+ * the source of truth: queued creates replay to the backend and the next
+ * pull restores canonical rows. Returns the purge count for logging.
+ */
+export declare function purgeNonCanonicalMenuCache(businessId: string): Promise<number>;

package/dist/reference/menu-apply.js

@@ -0,0 +1,289 @@
+/**
+ * Local application of menu commands to the durable reference cache.
+ *
+ * Used by (a) handleNodeCommand when this device executes a peer's menu
+ * command over LAN, and (b) the engine queue branch for optimistic local
+ * apply while fully offline. Shapes mirror the cloud fetchers
+ * (reference/service fetchFallback): menu:items payload {data:[...]},
+ * menu:categories payload {data:[...]} (or bare array — tolerated).
+ *
+ * Versions are intentionally left untouched: optimistic/LAN applies converge
+ * peers via explicit reference_data.changed events + reference_fetch (which
+ * serve payloads directly, no version compare). Real versions come from the
+ * backend when the command replays through the cloud path.
+ */
+import { openSyncDatabase } from "../db/connection";
+import { getReferenceData, setReferenceData } from "./operations";
+import { syncLogger } from "../utils/sync-logger";
+import { generateUUID } from "../utils/uuid";
+import { hlcToString, tickHLC, hlcFromString } from "../utils/hlc";
+import { getAppInstanceId } from "../adapters/devices";
+export const MENU_ITEM_KEY = "menu:items";
+export const MENU_CATEGORY_KEY = "menu:categories";
+function asArray(payload) {
+    if (Array.isArray(payload))
+        return payload;
+    const data = payload?.data;
+    return Array.isArray(data) ? data : [];
+}
+function withArray(payload, arr) {
+    if (Array.isArray(payload))
+        return arr;
+    if (payload && typeof payload === "object")
+        return { ...payload, data: arr };
+    return { data: arr };
+}
+/**
+ * Extract the caller-built cache record from a menu command payload. The
+ * reference cache holds backend-shaped records ONLY (MenuItem / MenuCategory
+ * exactly as the serializer returns them) — never wire payloads. Callers
+ * build the record alongside the wire payload; core performs no translation.
+ * A command without a record writes nothing (cloud convergence fills the
+ * cache on the next pull).
+ */
+function cacheRecord(payload) {
+    const rec = payload.cacheRecord;
+    if (!rec || typeof rec !== "object" || Array.isArray(rec))
+        return null;
+    return rec;
+}
+async function patchKey(businessId, key, patch) {
+    try {
+        const db = await openSyncDatabase();
+        const rec = await getReferenceData(db, businessId, key);
+        // Seed empty row if first-ever offline create before any pull.
+        if (!rec) {
+            const next = patch([]);
+            const hlc = hlcToString(tickHLC(Date.now(), null, getAppInstanceId()));
+            await setReferenceData(db, businessId, {
+                key,
+                version: hlc,
+                payload: withArray({ data: [] }, next),
+                downloadedAt: new Date().toISOString(),
+                lastEventId: `evt_${hlc}`,
+                lastHlc: hlc,
+            });
+            return true;
+        }
+        const next = patch(asArray(rec.payload));
+        const hlc = hlcToString(tickHLC(Date.now(), hlcFromString(rec.lastHlc ?? rec.version) ?? null, getAppInstanceId()));
+        await setReferenceData(db, businessId, {
+            key,
+            version: hlc,
+            payload: withArray(rec.payload, next),
+            downloadedAt: new Date().toISOString(),
+            lastEventId: `evt_${hlc}`,
+            lastHlc: hlc,
+        });
+        return true;
+    }
+    catch (e) {
+        syncLogger.debug("MenuApply", "local menu patch failed", { businessId, key, err: String(e) });
+        return false;
+    }
+}
+/**
+ * Apply a menu:* command to the local reference cache. Returns affected keys
+ * (for reference_data.changed fan-out) and whether anything was written.
+ * Idempotent by entity id: re-applying the same command converges.
+ */
+export async function applyMenuCommandLocal(businessId, command) {
+    const payload = (command.payload ?? {});
+    const idOf = (v) => (typeof v === "string" && v ? v : null);
+    switch (command.command_type) {
+        case "menu:create_item": {
+            const id = idOf(command.entity_id) ?? idOf(payload.id) ?? generateUUID();
+            const record = cacheRecord(payload);
+            if (!record) {
+                syncLogger.debug("MenuApply", "create_item without cacheRecord — skipping cache write", { businessId, id: command.entity_id });
+                return { keys: [MENU_ITEM_KEY], applied: false };
+            }
+            const item = { ...record, id };
+            const applied = await patchKey(businessId, MENU_ITEM_KEY, (arr) => {
+                stashPrior(arr, businessId, id);
+                return arr.some((o) => String(o.id) === id) ? arr.map((o) => (String(o.id) === id ? item : o)) : [...arr, item];
+            });
+            return { keys: [MENU_ITEM_KEY], applied };
+        }
+        case "menu:update_item": {
+            const id = idOf(command.entity_id) ?? idOf(payload.id) ?? idOf(payload.item_id);
+            if (!id)
+                return { keys: [MENU_ITEM_KEY], applied: false };
+            const record = cacheRecord(payload);
+            if (!record) {
+                syncLogger.debug("MenuApply", "update_item without cacheRecord — skipping cache write", { businessId, id });
+                return { keys: [MENU_ITEM_KEY], applied: false };
+            }
+            const applied = await patchKey(businessId, MENU_ITEM_KEY, (arr) => {
+                stashPrior(arr, businessId, id);
+                return arr.map((o) => (String(o.id) === id ? { ...record, id } : o));
+            });
+            return { keys: [MENU_ITEM_KEY], applied };
+        }
+        case "menu:delete_item": {
+            const id = idOf(command.entity_id) ?? idOf(payload.id);
+            if (!id)
+                return { keys: [MENU_ITEM_KEY], applied: false };
+            const applied = await patchKey(businessId, MENU_ITEM_KEY, (arr) => arr.filter((o) => String(o.id) !== id));
+            return { keys: [MENU_ITEM_KEY], applied };
+        }
+        case "menu:create_category": {
+            const id = idOf(command.entity_id) ?? idOf(payload.id) ?? generateUUID();
+            const record = cacheRecord(payload);
+            if (!record) {
+                syncLogger.debug("MenuApply", "create_category without cacheRecord — skipping cache write", { businessId });
+                return { keys: [MENU_CATEGORY_KEY], applied: false };
+            }
+            const cat = { ...record, id };
+            const applied = await patchKey(businessId, MENU_CATEGORY_KEY, (arr) => {
+                stashPrior(arr, businessId, id);
+                return arr.some((o) => String(o.id) === id) ? arr.map((o) => (String(o.id) === id ? cat : o)) : [...arr, cat];
+            });
+            return { keys: [MENU_CATEGORY_KEY], applied };
+        }
+        case "menu:update_category": {
+            const id = idOf(command.entity_id) ?? idOf(payload.id) ?? idOf(payload.category_id);
+            if (!id)
+                return { keys: [MENU_CATEGORY_KEY], applied: false };
+            const record = cacheRecord(payload);
+            if (!record) {
+                syncLogger.debug("MenuApply", "update_category without cacheRecord — skipping cache write", { businessId, id });
+                return { keys: [MENU_CATEGORY_KEY], applied: false };
+            }
+            const applied = await patchKey(businessId, MENU_CATEGORY_KEY, (arr) => {
+                stashPrior(arr, businessId, id);
+                return arr.map((o) => (String(o.id) === id ? { ...record, id } : o));
+            });
+            return { keys: [MENU_CATEGORY_KEY], applied };
+        }
+        case "menu:delete_category": {
+            const id = idOf(command.entity_id) ?? idOf(payload.id) ?? idOf(payload.category_id);
+            if (!id)
+                return { keys: [MENU_CATEGORY_KEY], applied: false };
+            const applied = await patchKey(businessId, MENU_CATEGORY_KEY, (arr) => arr.filter((o) => String(o.id) !== id));
+            return { keys: [MENU_CATEGORY_KEY], applied };
+        }
+        default:
+            return { keys: [], applied: false };
+    }
+}
+/**
+ * Prior-record stash for toast-and-revert: before overwriting a cached row,
+ * the previous record is kept in memory so a backend rejection can restore
+ * it. Creates stash a tombstone (revert deletes the row).
+ */
+const priorRecords = new Map();
+function stashPrior(arr, businessId, id) {
+    try {
+        const prev = arr.find((o) => String(o.id) === id);
+        priorRecords.set(`${businessId}:${id}`, prev ? { ...prev } : null);
+    }
+    catch { }
+}
+/**
+ * Revert an optimistic menu write after a definitive backend rejection:
+ * restores the stashed prior record, or deletes the row for creates.
+ * Peers converge via reference_fetch/pull on the next sync.
+ */
+export async function revertMenuCommand(businessId, commandType, entityId) {
+    const key = `${businessId}:${entityId}`;
+    try {
+        if (commandType === "menu:create_item") {
+            const applied = await patchKey(businessId, MENU_ITEM_KEY, (arr) => arr.filter((o) => String(o.id) !== entityId));
+            priorRecords.delete(key);
+            return applied;
+        }
+        if (commandType === "menu:update_item") {
+            const prior = priorRecords.get(key);
+            priorRecords.delete(key);
+            if (prior === undefined)
+                return false;
+            const applied = await patchKey(businessId, MENU_ITEM_KEY, (arr) => {
+                if (prior === null)
+                    return arr.filter((o) => String(o.id) !== entityId);
+                return arr.some((o) => String(o.id) === entityId)
+                    ? arr.map((o) => (String(o.id) === entityId ? { ...prior, id: entityId } : o))
+                    : [...arr, { ...prior, id: entityId }];
+            });
+            return applied;
+        }
+        if (commandType === "menu:create_category") {
+            const applied = await patchKey(businessId, MENU_CATEGORY_KEY, (arr) => arr.filter((o) => String(o.id) !== entityId));
+            priorRecords.delete(key);
+            return applied;
+        }
+        if (commandType === "menu:update_category") {
+            const prior = priorRecords.get(key);
+            priorRecords.delete(key);
+            if (prior === undefined)
+                return false;
+            const applied = await patchKey(businessId, MENU_CATEGORY_KEY, (arr) => {
+                if (prior === null)
+                    return arr.filter((o) => String(o.id) !== entityId);
+                return arr.some((o) => String(o.id) === entityId)
+                    ? arr.map((o) => (String(o.id) === entityId ? { ...prior, id: entityId } : o))
+                    : [...arr, { ...prior, id: entityId }];
+            });
+            return applied;
+        }
+    }
+    catch { }
+    return false;
+}
+/** Keys whose cache a menu command affects (for fan-out without applying). */
+export function menuCommandKeys(commandType) {
+    if (commandType.startsWith("menu:") && commandType.includes("categor"))
+        return [MENU_CATEGORY_KEY];
+    if (commandType.startsWith("menu:"))
+        return [MENU_ITEM_KEY];
+    return [];
+}
+function isCanonicalMenuItem(o) {
+    if (!o || typeof o !== "object")
+        return false;
+    const r = o;
+    const bp = r.basePrice;
+    return (typeof r.id === "string" &&
+        typeof r.name === "string" &&
+        !!bp &&
+        typeof bp.amountMinor === "number" &&
+        typeof bp.currencyCode === "string" &&
+        Array.isArray(r.variants) &&
+        Array.isArray(r.extras) &&
+        Array.isArray(r.dietary_tags));
+}
+/**
+ * One-time janitor: remove cached menu rows that are not backend-shaped
+ * MenuItems (written by older builds that cached raw wire payloads). This is
+ * explicit removal of invalid data — never translation. The outbox remains
+ * the source of truth: queued creates replay to the backend and the next
+ * pull restores canonical rows. Returns the purge count for logging.
+ */
+export async function purgeNonCanonicalMenuCache(businessId) {
+    try {
+        const db = await openSyncDatabase();
+        const rec = await getReferenceData(db, businessId, MENU_ITEM_KEY);
+        if (!rec)
+            return 0;
+        const arr = asArray(rec.payload);
+        const kept = arr.filter(isCanonicalMenuItem);
+        const purged = arr.length - kept.length;
+        if (purged === 0)
+            return 0;
+        const hlc = hlcToString(tickHLC(Date.now(), hlcFromString(rec.lastHlc ?? rec.version) ?? null, getAppInstanceId()));
+        await setReferenceData(db, businessId, {
+            key: MENU_ITEM_KEY,
+            version: hlc,
+            payload: withArray(rec.payload, kept),
+            downloadedAt: new Date().toISOString(),
+            lastEventId: `evt_${hlc}`,
+            lastHlc: hlc,
+        });
+        syncLogger.warn("MenuApply", "purged non-canonical cached menu rows", { businessId, purged, kept: kept.length });
+        return purged;
+    }
+    catch (e) {
+        syncLogger.debug("MenuApply", "menu cache purge failed", { businessId, err: String(e) });
+        return 0;
+    }
+}

package/dist/reference/menu-record.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Menu cache-record builders — the ONLY place MenuItem/MenuCategory records
+ * are constructed outside the backend.
+ *
+ * The reference cache holds backend-shaped records exactly as the serializer
+ * returns them (see TeincFoodBackend menu_serializer.ex). Form/mutation
+ * layers own every field at write time, so they build the record here —
+ * core never translates wire payloads into cache records.
+ */
+import type { MenuCategory, MenuItem } from "../types/api/menu.api";
+import type { QueryClient } from "@tanstack/react-query";
+export interface MenuItemRecordInput {
+    id?: string;
+    businessId: string;
+    name: string;
+    description?: string | null;
+    priceMinor: number;
+    currencyCode?: string;
+    categoryId: string;
+    categoryName?: string;
+    dietaryTags?: string[];
+    variants?: Array<{
+        id?: string;
+        name: string;
+        price_adjustment?: number;
+    }>;
+    extras?: Array<{
+        id?: string;
+        name: string;
+        price_minor?: number;
+    }>;
+    available?: boolean;
+    imageUrl?: string | null;
+    now?: string;
+}
+export declare function buildMenuItemRecord(input: MenuItemRecordInput): MenuItem;
+export interface MenuCategoryRecordInput {
+    id?: string;
+    name: string;
+    sort_order?: number;
+}
+export declare function buildMenuCategoryRecord(input: MenuCategoryRecordInput): MenuCategory;
+/** Every cached MenuItem for a business across cached + network queries. */
+export declare function getCachedMenuItems(qc: QueryClient, businessId: string): MenuItem[];
+export declare function getCachedMenuItem(qc: QueryClient, businessId: string, id: string): MenuItem | undefined;
+export declare function getCachedCategories(qc: QueryClient, businessId: string): MenuCategory[];
+export declare function getCachedCategoryName(qc: QueryClient, businessId: string, categoryId: string): string;
+export interface MenuItemEnvelopeInput extends MenuItemRecordInput {
+    /** Extra wire-only keys (e.g. entity id). */
+    wireExtra?: Record<string, unknown>;
+}
+/**
+ * Build the { wire, cacheRecord } pair for a menu item write. Callers pass
+ * backend adjustment-shaped variants; absolute form prices are converted by
+ * the caller (form layer owns both fields).
+ *
+ * Variant/extra ids are preserved when they are backend UUIDs. The backend
+ * update path deletes existing rows absent from the incoming list, so
+ * stripping ids on edit would wipe + recreate every variant/extra on each
+ * save (breaking any external references to those ids).
+ */
+export declare function buildMenuItemEnvelope(input: MenuItemEnvelopeInput): {
+    wire: Record<string, unknown>;
+    cacheRecord: MenuItem;
+};
+export declare function buildMenuCategoryEnvelope(input: MenuCategoryRecordInput): {
+    wire: Record<string, unknown>;
+    cacheRecord: MenuCategory;
+};

package/dist/reference/menu-record.js

@@ -0,0 +1,163 @@
+/**
+ * Menu cache-record builders — the ONLY place MenuItem/MenuCategory records
+ * are constructed outside the backend.
+ *
+ * The reference cache holds backend-shaped records exactly as the serializer
+ * returns them (see TeincFoodBackend menu_serializer.ex). Form/mutation
+ * layers own every field at write time, so they build the record here —
+ * core never translates wire payloads into cache records.
+ */
+import { generateUUID } from "../utils/uuid";
+import { CATALOG_KEYS } from "../catalog/hooks";
+export function buildMenuItemRecord(input) {
+    const currencyCode = input.currencyCode || "GHS";
+    const now = input.now ?? new Date().toISOString();
+    return {
+        id: input.id ?? generateUUID(),
+        name: input.name,
+        description: input.description ?? null,
+        basePrice: { amountMinor: input.priceMinor, currencyCode },
+        image_url: input.imageUrl ?? null,
+        is_available: input.available ?? true,
+        dietary_tags: input.dietaryTags ?? [],
+        category_id: input.categoryId,
+        business_id: input.businessId,
+        category: { id: input.categoryId, name: input.categoryName ?? "" },
+        variants: (input.variants ?? []).map((v) => ({
+            id: v.id ?? generateUUID(),
+            name: v.name,
+            // Matches backend serializer: variant price = base + adjustment.
+            price: { amountMinor: input.priceMinor + (v.price_adjustment ?? 0), currencyCode },
+        })),
+        extras: (input.extras ?? []).map((e) => ({
+            id: e.id ?? generateUUID(),
+            name: e.name,
+            pricingType: "fixed",
+            amountMinor: e.price_minor ?? 0,
+            currencyCode,
+        })),
+        inserted_at: now,
+        updated_at: now,
+    };
+}
+export function buildMenuCategoryRecord(input) {
+    return {
+        id: input.id ?? generateUUID(),
+        name: input.name,
+        sort_order: input.sort_order ?? 0,
+        is_global: false,
+        is_system: false,
+        pending_global_request: false,
+    };
+}
+// ─── Cache lookups (mutation layers read current records to build envelopes)
+function collectItems(blob, out) {
+    if (!blob || typeof blob !== "object")
+        return;
+    if (Array.isArray(blob)) {
+        for (const i of blob)
+            if (i?.id)
+                out.push(i);
+        return;
+    }
+    const rec = blob;
+    if (Array.isArray(rec.data))
+        collectItems(rec.data, out);
+    if (Array.isArray(rec.pages))
+        for (const p of rec.pages)
+            collectItems(p?.data, out);
+}
+/** Every cached MenuItem for a business across cached + network queries. */
+export function getCachedMenuItems(qc, businessId) {
+    const out = [];
+    try {
+        for (const [, data] of qc.getQueriesData({ queryKey: CATALOG_KEYS.items(businessId) })) {
+            collectItems(data, out);
+        }
+    }
+    catch { }
+    const seen = new Set();
+    return out.filter((i) => (seen.has(i.id) ? false : (seen.add(i.id), true)));
+}
+export function getCachedMenuItem(qc, businessId, id) {
+    return getCachedMenuItems(qc, businessId).find((i) => i.id === id);
+}
+function collectCategories(blob, out) {
+    if (!blob || typeof blob !== "object")
+        return;
+    if (Array.isArray(blob)) {
+        for (const c of blob)
+            if (c?.id)
+                out.push(c);
+        return;
+    }
+    const rec = blob;
+    if (Array.isArray(rec.data))
+        collectCategories(rec.data, out);
+}
+export function getCachedCategories(qc, businessId) {
+    const out = [];
+    try {
+        for (const [, data] of qc.getQueriesData({ queryKey: CATALOG_KEYS.categories(businessId) })) {
+            collectCategories(data, out);
+        }
+    }
+    catch { }
+    const seen = new Set();
+    return out.filter((c) => (seen.has(c.id) ? false : (seen.add(c.id), true)));
+}
+export function getCachedCategoryName(qc, businessId, categoryId) {
+    return getCachedCategories(qc, businessId).find((c) => c.id === categoryId)?.name ?? "";
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * A variant/extra id is only safe to send when it is a real backend UUID.
+ * Form-local ids (e.g. `local-<ts>`) must be omitted: the backend treats a
+ * missing/empty id as "insert new", but Repo.get/3 raises on a non-UUID.
+ */
+function wireId(id) {
+    return id && UUID_RE.test(id) ? id : undefined;
+}
+/**
+ * Build the { wire, cacheRecord } pair for a menu item write. Callers pass
+ * backend adjustment-shaped variants; absolute form prices are converted by
+ * the caller (form layer owns both fields).
+ *
+ * Variant/extra ids are preserved when they are backend UUIDs. The backend
+ * update path deletes existing rows absent from the incoming list, so
+ * stripping ids on edit would wipe + recreate every variant/extra on each
+ * save (breaking any external references to those ids).
+ */
+export function buildMenuItemEnvelope(input) {
+    const id = input.id ?? generateUUID();
+    const cacheRecord = buildMenuItemRecord({ ...input, id });
+    const wire = {
+        id,
+        name: input.name,
+        description: input.description ?? "",
+        price_minor: input.priceMinor,
+        category_id: input.categoryId,
+        currency_code: input.currencyCode ?? "GHS",
+        dietary_tags: input.dietaryTags ?? [],
+        variants: (input.variants ?? []).map((v) => {
+            const vid = wireId(v.id);
+            return vid
+                ? { id: vid, name: v.name, price_adjustment: v.price_adjustment ?? 0 }
+                : { name: v.name, price_adjustment: v.price_adjustment ?? 0 };
+        }),
+        extras: (input.extras ?? []).map((e) => {
+            const eid = wireId(e.id);
+            return eid
+                ? { id: eid, name: e.name, price_minor: e.price_minor ?? 0 }
+                : { name: e.name, price_minor: e.price_minor ?? 0 };
+        }),
+        available: input.available ?? true,
+        image_url: input.imageUrl ?? null,
+        ...(input.wireExtra ?? {}),
+    };
+    return { wire, cacheRecord };
+}
+export function buildMenuCategoryEnvelope(input) {
+    const cacheRecord = buildMenuCategoryRecord(input);
+    return { wire: { id: cacheRecord.id, name: input.name, ...(input.sort_order !== undefined ? { sort_order: input.sort_order } : {}) }, cacheRecord };
+}