@teincfood/core 0.1.0

package/dist/index.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * @teincfood/core — shared offline-first backbone
+ *
+ * Entry point. Re-exports types, sync engine, DB, reference service, repos and adapters.
+ * Host apps call `createTeincCore` once at bootstrap to wire platform adapters.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.referenceSyncService = exports.posRepository = exports.orderRepository = exports.orderSnapshotsService = exports.isLocalOrderNumber = exports.generateLocalCalloutNumber = exports.generateLocalOrderNumber = exports.buildCommand = exports.commandQueueService = exports.SyncEngine = exports.getSyncDatabase = exports.openSyncDatabase = exports.dbOps = void 0;
+exports.createTeincCore = createTeincCore;
+exports.getCoreEngine = getCoreEngine;
+// ── Types ──
+__exportStar(require("./types/api"), exports);
+__exportStar(require("./types/pos.types"), exports);
+// ── Utils ──
+__exportStar(require("./utils/constants"), exports);
+__exportStar(require("./utils/currency"), exports);
+__exportStar(require("./utils/error"), exports);
+__exportStar(require("./utils/uuid"), exports);
+__exportStar(require("./utils/sync-logger"), exports);
+// ── DB ──
+__exportStar(require("./db/migrations"), exports);
+exports.dbOps = __importStar(require("./db/operations"));
+var connection_1 = require("./db/connection");
+Object.defineProperty(exports, "openSyncDatabase", { enumerable: true, get: function () { return connection_1.openSyncDatabase; } });
+Object.defineProperty(exports, "getSyncDatabase", { enumerable: true, get: function () { return connection_1.getSyncDatabase; } });
+// ── Sync ──
+__exportStar(require("./sync/types"), exports);
+var engine_1 = require("./sync/engine");
+Object.defineProperty(exports, "SyncEngine", { enumerable: true, get: function () { return engine_1.SyncEngine; } });
+var command_queue_service_1 = require("./sync/command-queue.service");
+Object.defineProperty(exports, "commandQueueService", { enumerable: true, get: function () { return command_queue_service_1.commandQueueService; } });
+var command_builder_1 = require("./sync/command-builder");
+Object.defineProperty(exports, "buildCommand", { enumerable: true, get: function () { return command_builder_1.buildCommand; } });
+var order_number_1 = require("./sync/order-number");
+Object.defineProperty(exports, "generateLocalOrderNumber", { enumerable: true, get: function () { return order_number_1.generateLocalOrderNumber; } });
+Object.defineProperty(exports, "generateLocalCalloutNumber", { enumerable: true, get: function () { return order_number_1.generateLocalCalloutNumber; } });
+Object.defineProperty(exports, "isLocalOrderNumber", { enumerable: true, get: function () { return order_number_1.isLocalOrderNumber; } });
+var order_snapshots_service_1 = require("./sync/order-snapshots.service");
+Object.defineProperty(exports, "orderSnapshotsService", { enumerable: true, get: function () { return order_snapshots_service_1.orderSnapshotsService; } });
+__exportStar(require("./sync/pending-orders.service"), exports);
+// ── Repositories ──
+var order_repository_1 = require("./repositories/order.repository");
+Object.defineProperty(exports, "orderRepository", { enumerable: true, get: function () { return order_repository_1.orderRepository; } });
+var pos_repository_1 = require("./repositories/pos.repository");
+Object.defineProperty(exports, "posRepository", { enumerable: true, get: function () { return pos_repository_1.posRepository; } });
+// ── Reference ──
+__exportStar(require("./reference/types"), exports);
+var service_1 = require("./reference/service");
+Object.defineProperty(exports, "referenceSyncService", { enumerable: true, get: function () { return service_1.referenceSyncService; } });
+// ── Adapters (for host apps to supply) ──
+__exportStar(require("./adapters/sqlite"), exports);
+__exportStar(require("./adapters/kv"), exports);
+__exportStar(require("./adapters/connectivity"), exports);
+__exportStar(require("./adapters/http"), exports);
+__exportStar(require("./adapters/local-node"), exports);
+// ── Init helper ──
+const sqlite_1 = require("./adapters/sqlite");
+const kv_1 = require("./adapters/kv");
+const connectivity_1 = require("./adapters/connectivity");
+const http_1 = require("./adapters/http");
+const engine_2 = require("./sync/engine");
+const transport_rest_1 = require("./sync/transport-rest");
+const transport_local_node_1 = require("./sync/transport-local-node");
+let engine = null;
+function createTeincCore(config = {}) {
+    if (config.sqliteDriver)
+        (0, sqlite_1.setSqliteDriver)(config.sqliteDriver);
+    if (config.kvDriver)
+        (0, kv_1.setKVDriver)(config.kvDriver);
+    if (config.httpClient)
+        (0, http_1.setHttpClient)(config.httpClient);
+    if (config.initialConnectivity)
+        (0, connectivity_1.setConnectivityState)(config.initialConnectivity);
+    engine = new engine_2.SyncEngine({ transports: [transport_rest_1.restTransport, transport_local_node_1.localNodeTransport] });
+    return { engine };
+}
+function getCoreEngine() {
+    if (!engine)
+        throw new Error("TeincFood core not initialised. Call createTeincCore() first.");
+    return engine;
+}

package/dist/reference/api.d.ts

@@ -0,0 +1,10 @@
+/**
+ * API service for reference data synchronization.
+ *
+ * These endpoints are expected on the backend. If they are not available,
+ * the ReferenceSyncService falls back to legacy menu endpoints.
+ */
+import type { ReferenceDataKey, ReferenceVersionInfo, ReferenceChangeSet } from "./types";
+export declare function fetchReferenceVersions(businessId: string): Promise<ReferenceVersionInfo[]>;
+export declare function fetchReferenceData(businessId: string, keys: ReferenceDataKey[]): Promise<Record<ReferenceDataKey, unknown>>;
+export declare function fetchReferenceChanges<T>(businessId: string, key: ReferenceDataKey, fromVersion: string): Promise<ReferenceChangeSet<T>>;

package/dist/reference/api.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * API service for reference data synchronization.
+ *
+ * These endpoints are expected on the backend. If they are not available,
+ * the ReferenceSyncService falls back to legacy menu endpoints.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchReferenceVersions = fetchReferenceVersions;
+exports.fetchReferenceData = fetchReferenceData;
+exports.fetchReferenceChanges = fetchReferenceChanges;
+const http_1 = require("../adapters/http");
+async function fetchReferenceVersions(businessId) {
+    const response = await http_1.api.get(`/businesses/${businessId}/reference-versions`);
+    return response.data.data;
+}
+async function fetchReferenceData(businessId, keys) {
+    const response = await http_1.api.get(`/businesses/${businessId}/reference-data`, { params: { keys: keys.join(",") } });
+    return response.data.data;
+}
+async function fetchReferenceChanges(businessId, key, fromVersion) {
+    const response = await http_1.api.get(`/businesses/${businessId}/reference-changes`, { params: { key, from_version: fromVersion } });
+    return response.data.data;
+}

package/dist/reference/events.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Reference data change events.
+ *
+ * Bridges reference-data mutations into the Sync Engine event bus so that
+ * every device stays in sync:
+ *
+ *   - The device that mutates a reference-backed entity (e.g. a menu item)
+ *     publishes `reference_data.changed` via the Sync Engine.
+ *   - The reconciliation bridge relays that event to LAN clients when this
+ *     device is the Local Node.
+ *   - Any device that receives the event (locally or over the LAN) re-syncs
+ *     the affected reference keys and invalidates its React Query caches.
+ *
+ * This module intentionally does not import the Sync Engine at runtime (only
+ * as a type). The engine is registered via `registerReferenceEventEngine`, so
+ * `local-node/service.ts` can depend on this module without creating an
+ * import cycle (engine → transport → local-node/service → reference/events).
+ */
+import type { DomainEvent } from "../sync/types";
+import type { SyncEngine } from "../sync/engine";
+import type { ReferenceDataKey } from "./types";
+export declare const REFERENCE_CHANGED_EVENT_TYPE = "reference_data.changed";
+export interface ReferenceChangedEventPayload {
+    business_id: string;
+    keys: ReferenceDataKey[];
+}
+/** Register the Sync Engine used to publish reference change events. */
+export declare function registerReferenceEventEngine(syncEngine: SyncEngine): void;
+/**
+ * Register a callback used to invalidate React Query caches when reference
+ * data changes. Returns an unregister function. Mirrors
+ * `registerPendingOrdersInvalidator`.
+ */
+export declare function registerReferenceInvalidator(fn: () => void): () => void;
+/**
+ * Publish a `reference_data.changed` event so every device (including this
+ * one) re-syncs the affected keys. Called after a successful mutation of a
+ * reference-backed entity.
+ */
+export declare function emitReferenceChanged(businessId: string, keys: ReferenceDataKey[]): void;
+/**
+ * Apply a `reference_data.changed` event: re-sync the affected keys and
+ * invalidate caches. Idempotent — duplicate deliveries (local broadcast + LAN
+ * broadcast) are safe because the reference sync is version-aware and guarded
+ * by a single-flight flag. Errors are logged, never thrown, so a failed
+ * reference sync can never crash the LAN event loop.
+ */
+export declare function applyReferenceChangeEvent(event: DomainEvent, origin?: "local" | "lan"): Promise<void>;
+/**
+ * Best-effort reference data sync when connectivity recovers. Covers devices
+ * that missed the change event (offline, not on the LAN) — the next time they
+ * get internet they attempt to re-sync all default reference keys.
+ */
+export declare function syncReferenceDataOnReconnect(): Promise<void>;

package/dist/reference/events.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Reference data change events.
+ *
+ * Bridges reference-data mutations into the Sync Engine event bus so that
+ * every device stays in sync:
+ *
+ *   - The device that mutates a reference-backed entity (e.g. a menu item)
+ *     publishes `reference_data.changed` via the Sync Engine.
+ *   - The reconciliation bridge relays that event to LAN clients when this
+ *     device is the Local Node.
+ *   - Any device that receives the event (locally or over the LAN) re-syncs
+ *     the affected reference keys and invalidates its React Query caches.
+ *
+ * This module intentionally does not import the Sync Engine at runtime (only
+ * as a type). The engine is registered via `registerReferenceEventEngine`, so
+ * `local-node/service.ts` can depend on this module without creating an
+ * import cycle (engine → transport → local-node/service → reference/events).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REFERENCE_CHANGED_EVENT_TYPE = void 0;
+exports.registerReferenceEventEngine = registerReferenceEventEngine;
+exports.registerReferenceInvalidator = registerReferenceInvalidator;
+exports.emitReferenceChanged = emitReferenceChanged;
+exports.applyReferenceChangeEvent = applyReferenceChangeEvent;
+exports.syncReferenceDataOnReconnect = syncReferenceDataOnReconnect;
+const auth_1 = require("../adapters/auth");
+const business_1 = require("../adapters/business");
+const devices_1 = require("../adapters/devices");
+const uuid_1 = require("../utils/uuid");
+const sync_logger_1 = require("../utils/sync-logger");
+const service_1 = require("./service");
+exports.REFERENCE_CHANGED_EVENT_TYPE = "reference_data.changed";
+/** Injected Sync Engine singleton (set by the reconciliation bridge). */
+let engine = null;
+/** Register the Sync Engine used to publish reference change events. */
+function registerReferenceEventEngine(syncEngine) {
+    engine = syncEngine;
+}
+/** Invalidate TanStack Query caches after reference data is re-synced. */
+let invalidator = null;
+/**
+ * Register a callback used to invalidate React Query caches when reference
+ * data changes. Returns an unregister function. Mirrors
+ * `registerPendingOrdersInvalidator`.
+ */
+function registerReferenceInvalidator(fn) {
+    invalidator = fn;
+    return () => {
+        if (invalidator === fn)
+            invalidator = null;
+    };
+}
+/**
+ * Publish a `reference_data.changed` event so every device (including this
+ * one) re-syncs the affected keys. Called after a successful mutation of a
+ * reference-backed entity.
+ */
+function emitReferenceChanged(businessId, keys) {
+    if (!businessId || keys.length === 0)
+        return;
+    if (!engine)
+        return;
+    const user = auth_1.useAuthStore.getState().user;
+    const event = {
+        event_id: (0, uuid_1.generateEventId)(),
+        event_type: exports.REFERENCE_CHANGED_EVENT_TYPE,
+        event_version: "1.0",
+        timestamp: new Date().toISOString(),
+        device_id: (0, devices_1.getAppInstanceId)(),
+        user_id: user?.id ?? "anonymous",
+        entity_id: businessId,
+        payload: { business_id: businessId, keys },
+    };
+    engine.publish(event);
+}
+/**
+ * Apply a `reference_data.changed` event: re-sync the affected keys and
+ * invalidate caches. Idempotent — duplicate deliveries (local broadcast + LAN
+ * broadcast) are safe because the reference sync is version-aware and guarded
+ * by a single-flight flag. Errors are logged, never thrown, so a failed
+ * reference sync can never crash the LAN event loop.
+ */
+async function applyReferenceChangeEvent(event, origin = "local") {
+    try {
+        if (event.event_type !== exports.REFERENCE_CHANGED_EVENT_TYPE)
+            return;
+        const payload = event.payload;
+        const businessId = payload?.business_id;
+        const keys = payload?.keys;
+        if (!businessId || !keys || keys.length === 0)
+            return;
+        sync_logger_1.syncLogger.info("ReferenceChange", "Reference data changed", {
+            origin,
+            business_id: businessId,
+            keys,
+        });
+        const result = await service_1.referenceSyncService.sync({
+            businessId,
+            keys,
+            incremental: true,
+        });
+        if (result.failed.length > 0) {
+            sync_logger_1.syncLogger.warn("ReferenceChange", "Reference sync had failures", {
+                origin,
+                failed: result.failed,
+                errors: result.errors,
+            });
+        }
+        invalidator?.();
+    }
+    catch (error) {
+        sync_logger_1.syncLogger.error("ReferenceChange", "Failed to apply reference change event", {
+            error: String(error),
+            event_type: event.event_type,
+        });
+    }
+}
+/**
+ * Best-effort reference data sync when connectivity recovers. Covers devices
+ * that missed the change event (offline, not on the LAN) — the next time they
+ * get internet they attempt to re-sync all default reference keys.
+ */
+async function syncReferenceDataOnReconnect() {
+    const businessId = business_1.useBusinessStore.getState().activeBusiness?.id;
+    if (!businessId)
+        return;
+    try {
+        const result = await service_1.referenceSyncService.sync({
+            businessId,
+            incremental: true,
+        });
+        if (result.failed.length > 0) {
+            sync_logger_1.syncLogger.warn("ReferenceChange", "Reconnect sync had failures", {
+                failed: result.failed,
+            });
+        }
+    }
+    catch (error) {
+        sync_logger_1.syncLogger.error("ReferenceChange", "Reconnect sync failed", {
+            error: String(error),
+        });
+    }
+}

package/dist/reference/operations.d.ts

@@ -0,0 +1,11 @@
+/**
+ * SQLite operations for the business-scoped reference data cache.
+ */
+import type { SQLiteDatabase } from "../adapters/sqlite";
+import type { ReferenceDataKey, ReferenceDataRecord } from "./types";
+export declare function getReferenceData<T>(db: SQLiteDatabase, businessId: string, key: ReferenceDataKey): Promise<ReferenceDataRecord<T> | null>;
+export declare function getReferenceVersion(db: SQLiteDatabase, businessId: string, key: ReferenceDataKey): Promise<string | null>;
+export declare function setReferenceData<T>(db: SQLiteDatabase, businessId: string, record: ReferenceDataRecord<T>): Promise<void>;
+export declare function deleteReferenceData(db: SQLiteDatabase, businessId: string, key: ReferenceDataKey): Promise<void>;
+export declare function deleteReferenceDataForBusiness(db: SQLiteDatabase, businessId: string): Promise<void>;
+export declare function getAllReferenceDataKeys(db: SQLiteDatabase, businessId: string): Promise<ReferenceDataKey[]>;

package/dist/reference/operations.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * SQLite operations for the business-scoped reference data cache.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getReferenceData = getReferenceData;
+exports.getReferenceVersion = getReferenceVersion;
+exports.setReferenceData = setReferenceData;
+exports.deleteReferenceData = deleteReferenceData;
+exports.deleteReferenceDataForBusiness = deleteReferenceDataForBusiness;
+exports.getAllReferenceDataKeys = getAllReferenceDataKeys;
+async function getReferenceData(db, businessId, key) {
+    const row = await db.getFirstAsync("SELECT * FROM reference_data WHERE business_id = ? AND key = ?;", businessId, key);
+    if (!row)
+        return null;
+    return {
+        key: row.key,
+        version: row.version,
+        payload: JSON.parse(row.payload),
+        downloadedAt: row.downloaded_at,
+    };
+}
+async function getReferenceVersion(db, businessId, key) {
+    const row = await db.getFirstAsync("SELECT version FROM reference_data WHERE business_id = ? AND key = ?;", businessId, key);
+    return row?.version ?? null;
+}
+async function setReferenceData(db, businessId, record) {
+    await db.runAsync(`
+      INSERT INTO reference_data (business_id, key, version, payload, downloaded_at)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(business_id, key) DO UPDATE SET
+        version = excluded.version,
+        payload = excluded.payload,
+        downloaded_at = excluded.downloaded_at;
+    `, businessId, record.key, record.version, JSON.stringify(record.payload), record.downloadedAt);
+}
+async function deleteReferenceData(db, businessId, key) {
+    await db.runAsync("DELETE FROM reference_data WHERE business_id = ? AND key = ?;", businessId, key);
+}
+async function deleteReferenceDataForBusiness(db, businessId) {
+    await db.runAsync("DELETE FROM reference_data WHERE business_id = ?;", businessId);
+}
+async function getAllReferenceDataKeys(db, businessId) {
+    const rows = await db.getAllAsync("SELECT key FROM reference_data WHERE business_id = ? ORDER BY key;", businessId);
+    return rows.map((r) => r.key);
+}

package/dist/reference/service.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Reference Data Synchronization Service.
+ *
+ * Responsible for downloading, versioning, and caching reference data
+ * (menus, categories, modifiers, taxes, printers, etc.) locally.
+ *
+ * This service is separate from the Sync Engine, which handles transactional
+ * commands and events.
+ */
+import type { ReferenceDataKey, ReferenceSyncOptions, ReferenceSyncResult, ReferenceDataRecord } from "./types";
+declare class ReferenceSyncService {
+    private isSyncing;
+    sync(options: ReferenceSyncOptions): Promise<ReferenceSyncResult>;
+    private syncKey;
+    private fetchFallback;
+    /**
+     * Download every image referenced by the given cached reference keys into
+     * durable local storage, then prune orphaned files. Covers menu item photos
+     * and the business logo/cover. Idempotent — already-cached images are
+     * skipped. Errors never propagate: a failed download must not fail the sync.
+     */
+    private cacheReferenceImages;
+    private hashPayload;
+    getCached<T>(businessId: string, key: ReferenceDataKey): Promise<ReferenceDataRecord<T> | null>;
+}
+export declare const referenceSyncService: ReferenceSyncService;
+export {};