@teincfood/core 0.1.0

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

@@ -0,0 +1,253 @@
+"use strict";
+/**
+ * Command Queue Service.
+ *
+ * Durable SQLite outbox for commands that cannot be executed immediately.
+ * Responsibilities:
+ *   - Persist commands when the cloud and Local Node are both unavailable.
+ *   - Generate local order numbers for offline `order:create` commands.
+ *   - Replay queued commands when a transport becomes available.
+ *   - Provide optimistic domain events so the UI can render pending orders.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commandQueueService = void 0;
+const connection_1 = require("../db/connection");
+const operations_1 = require("../db/operations");
+const sync_logger_1 = require("../utils/sync-logger");
+const uuid_1 = require("../utils/uuid");
+const order_number_1 = require("./order-number");
+const MAX_RETRIES = 5;
+function buildOptimisticEvent(command) {
+    const payload = command.payload;
+    return {
+        event_id: (0, uuid_1.generateEventId)(),
+        event_type: `${command.command_type.replace(":", ".")}_queued`,
+        event_version: "1.0",
+        entity_id: command.entity_id ?? command.command_id,
+        user_id: command.user_id,
+        device_id: command.device_id,
+        payload: command.command_type === "order:create"
+            ? buildOptimisticOrder(command, payload)
+            : {
+                ...payload,
+                command_id: command.command_id,
+                status: "pending",
+            },
+        timestamp: new Date().toISOString(),
+    };
+}
+function buildOptimisticOrder(command, payload) {
+    const items = payload.items ?? [];
+    const totalMinor = payload.total_minor ?? 0;
+    const now = new Date().toISOString();
+    const orderNumber = payload.order_number ?? (0, order_number_1.generateLocalOrderNumber)();
+    return {
+        id: command.entity_id ?? command.command_id,
+        order_number: orderNumber,
+        callout_number: (0, order_number_1.generateLocalCalloutNumber)(),
+        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",
+        delivery_id: null,
+        delivery_status: null,
+        is_paid: payload.pos_payment_method === "cash",
+        payment: {
+            is_paid: payload.pos_payment_method === "cash",
+            reference: null,
+            amount_minor: totalMinor,
+            currency: "GHS",
+            paid_at: payload.pos_payment_method === "cash" ? now : null,
+        },
+        payment_mode: "pos_cash",
+        total_minor: totalMinor,
+        subtotal_minor: totalMinor,
+        delivery_fee_minor: 0,
+        tax_minor: 0,
+        tip_minor: null,
+        discount_minor: 0,
+        promo_code: null,
+        tax_lines: [],
+        currency: "GHS",
+        currency_code: "GHS",
+        business_id: command.business_id,
+        business: null,
+        delivery_address: null,
+        delivery_lat: null,
+        delivery_lng: null,
+        user: null,
+        items: items.map((item, index) => ({
+            id: `tmp-${command.command_id}-${index}`,
+            menu_item: { id: item.menu_item_id, name: "" },
+            quantity: item.quantity,
+            unit_price: 0,
+            subtotal: 0,
+            addons: [],
+        })),
+        inserted_at: now,
+    };
+}
+/**
+ * If a command creates an order and we are offline, inject a local order number
+ * into the payload so the UI and receipt printers have a stable identifier.
+ */
+function injectLocalOrderNumber(command) {
+    if (command.command_type !== "order:create")
+        return command;
+    const payload = command.payload;
+    if (payload.order_number)
+        return command;
+    return {
+        ...command,
+        payload: {
+            ...payload,
+            order_number: (0, order_number_1.generateLocalOrderNumber)(),
+        },
+    };
+}
+class CommandQueueService {
+    constructor() {
+        this.replaying = false;
+        this.syncEngine = null;
+    }
+    setSyncEngine(engine) {
+        this.syncEngine = engine;
+    }
+    /**
+     * Enqueue a command because no transport is currently available.
+     * Returns an optimistic domain event so the caller can update the UI.
+     */
+    async enqueue(command) {
+        const db = (0, connection_1.getSyncDatabase)();
+        const preparedCommand = injectLocalOrderNumber(command);
+        await (0, operations_1.insertCommand)(db, { command: preparedCommand, status: "pending" });
+        sync_logger_1.syncLogger.command(preparedCommand, "queued");
+        const pending = await (0, operations_1.getPendingCommands)(db, Number.MAX_SAFE_INTEGER);
+        sync_logger_1.syncLogger.info("CommandQueueService", "Command queued offline", {
+            command_id: preparedCommand.command_id,
+            command_type: preparedCommand.command_type,
+            order_number: preparedCommand.payload.order_number ?? null,
+            outbox_size: pending.length,
+        });
+        const event = buildOptimisticEvent(preparedCommand);
+        sync_logger_1.syncLogger.info("CommandQueueService", "Optimistic event built", {
+            event_type: event.event_type,
+            entity_id: event.entity_id,
+            order_number: event.payload.order_number ?? null,
+            status: event.payload.status,
+        });
+        // Persist the optimistic order so it survives app restarts and can be
+        // rehydrated (and shown) while still offline.
+        if (preparedCommand.command_type === "order:create") {
+            try {
+                await (0, operations_1.insertEvent)(db, { event, origin: "local" });
+            }
+            catch (error) {
+                sync_logger_1.syncLogger.error("CommandQueueService", "Failed to persist optimistic event", {
+                    error: String(error),
+                });
+            }
+        }
+        return event;
+    }
+    /**
+     * Try to execute a single pending command through the current transport.
+     */
+    async processCommand(command) {
+        const db = (0, connection_1.getSyncDatabase)();
+        const parsedCommand = {
+            command_id: command.command_id,
+            command_type: command.command_type,
+            command_version: command.command_version,
+            business_id: command.business_id,
+            entity_id: command.entity_id,
+            user_id: command.user_id,
+            device_id: command.device_id,
+            timestamp: command.timestamp,
+            payload: command.payload,
+        };
+        if (command.retry_count >= MAX_RETRIES) {
+            await (0, operations_1.updateCommandStatus)(db, command.command_id, "failed", "Max retry count exceeded");
+            return;
+        }
+        if (!this.syncEngine) {
+            throw new Error("CommandQueueService: SyncEngine not initialized");
+        }
+        await (0, operations_1.markCommandInFlight)(db, command.command_id);
+        try {
+            const events = await this.syncEngine.execute(parsedCommand);
+            await (0, operations_1.updateCommandStatus)(db, command.command_id, "completed");
+            sync_logger_1.syncLogger.command(parsedCommand, "completed", {
+                event_count: events.length,
+            });
+            sync_logger_1.syncLogger.info("CommandQueueService", "Queued command replayed", {
+                command_id: command.command_id,
+                command_type: command.command_type,
+                event_count: events.length,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            await (0, operations_1.updateCommandStatus)(db, command.command_id, "failed", message);
+            sync_logger_1.syncLogger.command(parsedCommand, "failed", { error: message });
+            throw error;
+        }
+    }
+    /**
+     * Replay all pending commands in order. Stops on the first failure to keep
+     * ordering consistent; the next replay will retry from the failed command.
+     */
+    async replay() {
+        if (this.replaying) {
+            sync_logger_1.syncLogger.debug("CommandQueueService", "Replay already in progress");
+            return;
+        }
+        this.replaying = true;
+        try {
+            // Await open (not getSyncDatabase) so a cold-start replay triggered by a
+            // connectivity event that fires before the DB open completes does not
+            // throw "Sync database not initialized".
+            const db = await (0, connection_1.openSyncDatabase)();
+            const pending = await (0, operations_1.getPendingCommands)(db);
+            if (pending.length === 0)
+                return;
+            sync_logger_1.syncLogger.info("CommandQueueService", "Replaying commands", {
+                count: pending.length,
+            });
+            for (const command of pending) {
+                try {
+                    await this.processCommand(command);
+                }
+                catch {
+                    // Stop replay on first failure; retry will happen on next trigger.
+                    break;
+                }
+            }
+        }
+        finally {
+            this.replaying = false;
+        }
+    }
+    /**
+     * Cancel a queued command that has not yet been transmitted.
+     */
+    async cancel(commandId) {
+        const db = (0, connection_1.getSyncDatabase)();
+        await (0, operations_1.deleteCommand)(db, commandId);
+        sync_logger_1.syncLogger.debug("CommandQueueService", "Command cancelled", {
+            commandId,
+        });
+    }
+    /**
+     * Return the number of commands currently in the outbox.
+     */
+    async getPendingCount() {
+        const db = (0, connection_1.getSyncDatabase)();
+        const commands = await (0, operations_1.getPendingCommands)(db, Number.MAX_SAFE_INTEGER);
+        return commands.length;
+    }
+}
+exports.commandQueueService = new CommandQueueService();

package/dist/sync/engine.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Sync Engine orchestrator.
+ *
+ * Phase 1 responsibility: receive commands from repositories and route them
+ * to the active transport (currently REST only).
+ *
+ * Future phases will add:
+ *   - connectivity-aware transport selection
+ *   - command outbox persistence
+ *   - replay
+ *   - Local Node transport
+ *   - cloud reconciliation
+ */
+import type { Command, DomainEvent, Transport } from "./types";
+interface SyncEngineOptions {
+    /** Ordered list of transports the engine may use. */
+    transports: Transport[];
+}
+export declare class SyncEngine {
+    private transports;
+    private eventSubscribers;
+    constructor(options: SyncEngineOptions);
+    /**
+     * Execute a command through the appropriate transport.
+     *
+     * Transport selection:
+     *   - Cloud reachable and REST transport available → REST
+     *   - Local Node enabled and available → LocalNodeTransport
+     *   - Otherwise queue locally and return an optimistic event
+     *
+     * Cloud commands are raced against CLOUD_COMMAND_TIMEOUT_MS so a slow
+     * 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[]>;
+    /**
+     * Trigger replay of queued commands when connectivity returns.
+     */
+    replayQueuedCommands(): Promise<void>;
+    subscribe(handler: (event: DomainEvent) => void): () => void;
+    /**
+     * Publish a notification event to local subscribers without a transport
+     * round-trip. Used for cross-device notifications (e.g. reference data
+     * changed) that are not backed by a command: the event is broadcast locally
+     * so the reconciliation bridge can relay it to LAN clients.
+     */
+    publish(event: DomainEvent): void;
+    private resolveStrategy;
+    private selectTransport;
+    private broadcast;
+}
+export declare const syncEngine: SyncEngine;
+export {};

package/dist/sync/engine.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Sync Engine orchestrator.
+ *
+ * Phase 1 responsibility: receive commands from repositories and route them
+ * to the active transport (currently REST only).
+ *
+ * Future phases will add:
+ *   - connectivity-aware transport selection
+ *   - command outbox persistence
+ *   - replay
+ *   - Local Node transport
+ *   - cloud reconciliation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncEngine = exports.SyncEngine = void 0;
+const transport_rest_1 = require("./transport-rest");
+const transport_local_node_1 = require("./transport-local-node");
+const command_queue_service_1 = require("./command-queue.service");
+const connectivity_1 = require("../adapters/connectivity");
+const http_1 = require("../adapters/http");
+const sync_logger_1 = require("../utils/sync-logger");
+const constants_1 = require("../utils/constants");
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`Timed out after ${ms}ms`));
+        }, ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+class SyncEngine {
+    constructor(options) {
+        this.eventSubscribers = [];
+        this.transports = options.transports;
+    }
+    /**
+     * Execute a command through the appropriate transport.
+     *
+     * Transport selection:
+     *   - Cloud reachable and REST transport available → REST
+     *   - Local Node enabled and available → LocalNodeTransport
+     *   - Otherwise queue locally and return an optimistic event
+     *
+     * Cloud commands are raced against CLOUD_COMMAND_TIMEOUT_MS so a slow
+     * 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) {
+        sync_logger_1.syncLogger.command(command, "issued");
+        let strategy = this.resolveStrategy(command);
+        const { isCloudReachable, isOnline } = (0, connectivity_1.getConnectivityState)();
+        sync_logger_1.syncLogger.info("SyncEngine", "Command strategy resolved", {
+            command_id: command.command_id,
+            command_type: command.command_type,
+            strategy,
+            isCloudReachable,
+            isOnline,
+            cloud_available: transport_rest_1.restTransport.isAvailable(),
+            lan_available: transport_local_node_1.localNodeTransport.isAvailable(),
+        });
+        if (strategy === "queue") {
+            const event = await command_queue_service_1.commandQueueService.enqueue(command);
+            this.broadcast(event);
+            return [event];
+        }
+        if (strategy === "cloud") {
+            try {
+                const events = await withTimeout(transport_rest_1.restTransport.execute(command), constants_1.CLOUD_COMMAND_TIMEOUT_MS);
+                for (const event of events) {
+                    this.broadcast(event);
+                }
+                sync_logger_1.syncLogger.command(command, "completed", {
+                    event_count: events.length,
+                });
+                // Cloud just worked: it is reachable again. Mark it so future commands
+                // go cloud-first, and replay anything queued during the outage.
+                (0, connectivity_1.setConnectivityState)({ isCloudReachable: "reachable" });
+                this.replayQueuedCommands().catch((error) => {
+                    sync_logger_1.syncLogger.error("SyncEngine", "Replay after cloud success failed", {
+                        error: String(error),
+                    });
+                });
+                return events;
+            }
+            catch (error) {
+                // Definitive server rejection (4xx): the backend answered with a real
+                // decision (e.g. PAYMENT_REQUIRED, FORBIDDEN). Surface it to the
+                // caller instead of masking it as a connectivity problem and silently
+                // queueing a command that can never succeed.
+                if (error instanceof http_1.ApiError && error.status >= 400 && error.status < 500) {
+                    sync_logger_1.syncLogger.warn("SyncEngine", "Cloud command rejected by server", {
+                        command_type: command.command_type,
+                        command_id: command.command_id,
+                        status: error.status,
+                        message: error.message,
+                    });
+                    throw error;
+                }
+                // Cloud is slow or unreachable: mark it and fall back to the Local
+                // Node or the outbox so the terminal stays responsive.
+                sync_logger_1.syncLogger.warn("SyncEngine", "Cloud command timed out, falling back", {
+                    command_type: command.command_type,
+                    error: String(error),
+                });
+                (0, connectivity_1.setConnectivityState)({ isCloudReachable: "unreachable" });
+                strategy = this.resolveStrategy(command);
+                if (strategy === "queue") {
+                    const event = await command_queue_service_1.commandQueueService.enqueue(command);
+                    this.broadcast(event);
+                    return [event];
+                }
+                sync_logger_1.syncLogger.info("SyncEngine", "Cloud timed out, using LAN fallback", {
+                    command_id: command.command_id,
+                    command_type: command.command_type,
+                    strategy,
+                });
+            }
+        }
+        const transport = this.selectTransport(command, strategy);
+        sync_logger_1.syncLogger.info("SyncEngine", "Executing via transport", {
+            command_id: command.command_id,
+            command_type: command.command_type,
+            strategy,
+            transport: transport.name,
+        });
+        const events = await transport.execute(command);
+        for (const event of events) {
+            this.broadcast(event);
+        }
+        sync_logger_1.syncLogger.command(command, "completed", {
+            event_count: events.length,
+            transport: transport.name,
+        });
+        return events;
+    }
+    /**
+     * Trigger replay of queued commands when connectivity returns.
+     */
+    async replayQueuedCommands() {
+        await command_queue_service_1.commandQueueService.replay();
+    }
+    subscribe(handler) {
+        this.eventSubscribers.push(handler);
+        return () => {
+            const index = this.eventSubscribers.indexOf(handler);
+            if (index > -1) {
+                this.eventSubscribers.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * Publish a notification event to local subscribers without a transport
+     * round-trip. Used for cross-device notifications (e.g. reference data
+     * changed) that are not backed by a command: the event is broadcast locally
+     * so the reconciliation bridge can relay it to LAN clients.
+     */
+    publish(event) {
+        this.broadcast(event);
+    }
+    resolveStrategy(_command) {
+        const { isCloudReachable, isOnline } = (0, connectivity_1.getConnectivityState)();
+        // Cloud-first when we believe it is reachable OR we have not yet verified
+        // it (unknown). Only a confirmed "unreachable" status falls back to the
+        // Local Node / outbox. Commands issued on a healthy connection must never
+        // get stuck in the local outbox.
+        if ((isCloudReachable === "reachable" || isCloudReachable === "unknown") &&
+            transport_rest_1.restTransport.isAvailable()) {
+            return "cloud";
+        }
+        // Local Node fallback when enabled and connected.
+        if (transport_local_node_1.localNodeTransport.isAvailable()) {
+            return "local_node";
+        }
+        // No network at all: queue immediately.
+        if (!isOnline) {
+            return "queue";
+        }
+        // Network present but cloud status unknown or unreachable. Try cloud first;
+        // a failed HTTP call will bubble up and the caller (e.g. queue replay) can
+        // decide to retry. New commands issued while cloud is unknown are queued to
+        // avoid blocking the UI on a flaky connection.
+        if (isCloudReachable === "unreachable") {
+            return "queue";
+        }
+        return "cloud";
+    }
+    selectTransport(_command, strategy) {
+        if (strategy === "local_node" && transport_local_node_1.localNodeTransport.isAvailable()) {
+            return transport_local_node_1.localNodeTransport;
+        }
+        if (strategy === "cloud" && transport_rest_1.restTransport.isAvailable()) {
+            return transport_rest_1.restTransport;
+        }
+        const transport = this.transports.find((t) => t.isAvailable()) ?? this.transports[0];
+        if (!transport) {
+            throw new Error("SyncEngine: no transports configured");
+        }
+        return transport;
+    }
+    broadcast(event) {
+        sync_logger_1.syncLogger.event(event, "broadcast");
+        this.eventSubscribers.forEach((handler) => handler(event));
+    }
+}
+exports.SyncEngine = SyncEngine;
+exports.syncEngine = new SyncEngine({
+    transports: [transport_rest_1.restTransport, transport_local_node_1.localNodeTransport],
+});
+command_queue_service_1.commandQueueService.setSyncEngine(exports.syncEngine);

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

@@ -0,0 +1,20 @@
+/**
+ * Local order number allocation for offline/LAN operation.
+ *
+ * When the cloud is unreachable, the Local Node (or the local device if there
+ * is no Local Node) assigns temporary order numbers with the prefix
+ * `TFL-YYYYMMDD-NNNN`. These are reconciled with permanent cloud order numbers
+ * once connectivity returns.
+ */
+/**
+ * Generate a local order number for offline-created orders.
+ */
+export declare function generateLocalOrderNumber(date?: Date): string;
+/**
+ * Generate a local callout number for offline-created orders.
+ */
+export declare function generateLocalCalloutNumber(date?: Date): number;
+/**
+ * Check whether an order number was locally allocated.
+ */
+export declare function isLocalOrderNumber(orderNumber: string): boolean;

package/dist/sync/order-number.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Local order number allocation for offline/LAN operation.
+ *
+ * When the cloud is unreachable, the Local Node (or the local device if there
+ * is no Local Node) assigns temporary order numbers with the prefix
+ * `TFL-YYYYMMDD-NNNN`. These are reconciled with permanent cloud order numbers
+ * once connectivity returns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateLocalOrderNumber = generateLocalOrderNumber;
+exports.generateLocalCalloutNumber = generateLocalCalloutNumber;
+exports.isLocalOrderNumber = isLocalOrderNumber;
+const kv_1 = require("../adapters/kv");
+const LOCAL_ORDER_SEQ_KEY = "local_order_sequence";
+const LOCAL_CALLOUT_SEQ_KEY = "local_callout_sequence";
+function formatDatePart(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}${month}${day}`;
+}
+function getNextSequence(datePart, key) {
+    const stored = (0, kv_1.getItemSync)(key);
+    const map = stored ?? {};
+    const next = (map[datePart] ?? 0) + 1;
+    map[datePart] = next;
+    // Keep only the last 7 days to avoid unbounded growth.
+    const cutoff = String(Number(datePart) - 7);
+    for (const mapKey of Object.keys(map)) {
+        if (mapKey < cutoff) {
+            delete map[mapKey];
+        }
+    }
+    (0, kv_1.setItemSync)(key, map);
+    return next;
+}
+/**
+ * Generate a local order number for offline-created orders.
+ */
+function generateLocalOrderNumber(date = new Date()) {
+    const datePart = formatDatePart(date);
+    const seq = getNextSequence(datePart, LOCAL_ORDER_SEQ_KEY);
+    return `TFL-${datePart}-${String(seq).padStart(4, "0")}`;
+}
+/**
+ * Generate a local callout number for offline-created orders.
+ */
+function generateLocalCalloutNumber(date = new Date()) {
+    const datePart = formatDatePart(date);
+    return getNextSequence(datePart, LOCAL_CALLOUT_SEQ_KEY);
+}
+/**
+ * Check whether an order number was locally allocated.
+ */
+function isLocalOrderNumber(orderNumber) {
+    return orderNumber.startsWith("TFL-");
+}

package/dist/sync/order-snapshots.service.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Durable order read-model.
+ *
+ * Bridges order events and fetched order lists into the SQLite
+ * `entity_snapshots` read model so a restaurant can see current + recent
+ * orders offline (survives restart and logout) and refresh them once a
+ * connection is re-established.
+ *
+ * Two sources feed the read model:
+ *   1. Incoming order/delivery events (cloud WebSocket or LAN relay) are
+ *      persisted to the events journal and used to patch the latest status of
+ *      a known order.
+ *   2. Successful order list fetches are written through as snapshots so the
+ *      exact list last seen while online is available offline.
+ */
+import type { DomainEvent } from "./types";
+import type { SellerOrder } from "../types/api/seller.api";
+declare class OrderSnapshotsService {
+    /**
+     * Persist an order/delivery event into the durable event journal and patch
+     * the read model. Returns true if it was an order event (idempotent for
+     * duplicates).
+     */
+    persistOrderEvent(event: DomainEvent, origin: "local" | "lan" | "cloud"): Promise<boolean>;
+    /**
+     * Patch the latest status of a known order inside every list snapshot for the
+     * business, so offline devices see live status changes without a refetch.
+     */
+    private applyOrderStatusToReadModel;
+    /**
+     * Write through a fetched order list so it is available offline. Used by the
+     * seller and POS order queries. `scope` distinguishes complementary lists
+     * (e.g. the unfiltered recent list) within a business.
+     */
+    persistSellerOrders(businessId: string, scope: string, orders: SellerOrder[]): Promise<void>;
+    /**
+     * Read a persisted order list from the offline read model.
+     */
+    getSellerList(businessId: string, scope: string): Promise<SellerOrder[] | null>;
+    /**
+     * Prune snapshots outside the retention window. Call on startup.
+     */
+    pruneOld(): Promise<void>;
+}
+export declare const orderSnapshotsService: OrderSnapshotsService;
+export {};