@teincfood/core 0.10.17 → 0.10.19

package/dist/adapters/services.d.ts

@@ -36,7 +36,7 @@ export declare const sellerService: {
     }>;
 };
 export declare const kioskService: {
-    assignKioskOrderToRider: (_orderId: string, _riderId: string) => Promise<unknown>;
+    assignKioskOrderToRider: (_orderId: string, _riderId: string, _idempotencyKey?: string) => Promise<unknown>;
 };
 export declare const menuService: {
     fetchBusinessMenuItems: (_businessId: string, _page: number) => Promise<unknown>;

package/dist/adapters/services.js

@@ -54,7 +54,7 @@ export const sellerService = {
 };
 // kiosk.service
 export const kioskService = {
-    assignKioskOrderToRider: async (_orderId, _riderId) => {
+    assignKioskOrderToRider: async (_orderId, _riderId, _idempotencyKey) => {
         notImpl("kioskService.assignKioskOrderToRider");
     },
 };

package/dist/index.d.ts

@@ -59,7 +59,7 @@ export * from "./sync/command-builder";
 export { commandQueueService } from "./sync/command-queue.service";
 export { buildCommand } from "./sync/command-builder";
 export { generateLocalOrderNumber, generateLocalCalloutNumber, isLocalOrderNumber, generateOrderNumber, generateOrderNumberForBusiness, isOfflineOrderNumber, parseOrderNumber, resetCalloutForTests, } from "./sync/order-number";
-export { deviceLeaseService, getDeviceNumber, isOnlineOnly, ensureLease } from "./sync/device-lease.service";
+export { deviceLeaseService, getDeviceNumber, isOnlineOnly, ensureLease, getLastLeaseFailure, type DeviceLeaseFailure, } from "./sync/device-lease.service";
 export { useDeviceLease, ensureDeviceLease } from "./sync/use-device-lease";
 export { getStartupReadiness, ensureStartupReady, REQUIRED_ORDER_KEYS, type StartupReadiness, } from "./sync/startup-readiness";
 export { useStartupReadiness, type UseStartupReadinessOptions, type UseStartupReadinessResult, } from "./hooks/startup-readiness.hooks";

package/dist/index.js

@@ -61,7 +61,7 @@ export * from "./sync/command-builder";
 export { commandQueueService } from "./sync/command-queue.service";
 export { buildCommand } from "./sync/command-builder";
 export { generateLocalOrderNumber, generateLocalCalloutNumber, isLocalOrderNumber, generateOrderNumber, generateOrderNumberForBusiness, isOfflineOrderNumber, parseOrderNumber, resetCalloutForTests, } from "./sync/order-number";
-export { deviceLeaseService, getDeviceNumber, isOnlineOnly, ensureLease } from "./sync/device-lease.service";
+export { deviceLeaseService, getDeviceNumber, isOnlineOnly, ensureLease, getLastLeaseFailure, } from "./sync/device-lease.service";
 export { useDeviceLease, ensureDeviceLease } from "./sync/use-device-lease";
 export { getStartupReadiness, ensureStartupReady, REQUIRED_ORDER_KEYS, } from "./sync/startup-readiness";
 export { useStartupReadiness, } from "./hooks/startup-readiness.hooks";

package/dist/repositories/order.repository.js

@@ -141,8 +141,12 @@ export const orderRepository = {
             commandType: "delivery:assign",
             businessId: input.businessId,
             entityId: input.orderId,
-            payload: { rider_id: input.riderId },
+            payload: { rider_id: input.riderId, idempotency_key: "" },
         });
+        // One user action = one stable key. Replays of this command (timeout,
+        // reconnect, LAN relay) must converge on the same delivery instead of
+        // creating another one.
+        command.payload.idempotency_key = command.command_id;
         const events = await syncEngine.execute(command);
         const event = events[0];
         if (!event) {

package/dist/sync/device-lease.service.d.ts

@@ -4,6 +4,25 @@
  * KV persists device_number per businessId.
  */
 import { getAppInstanceIdAsync } from "../adapters/devices";
+/**
+ * Why the last device-lease attempt failed. Surfaced by startup readiness so a
+ * plan/terminal limit is not reported as "offline data incomplete".
+ */
+export interface DeviceLeaseFailure {
+    code: "TERMINAL_LIMIT_REACHED" | "DEVICE_LIMIT_REACHED" | "AUTH_REQUIRED" | "OFFLINE" | "LEASE_FAILED";
+    message: string;
+    status?: number;
+    limit?: number;
+    current?: number;
+}
+export declare function getLastLeaseFailure(businessId: string): DeviceLeaseFailure | null;
+/**
+ * Normalise the HTTP-client error into a user-presentable lease failure.
+ * Desktop injects its own ApiError shape; mobile/core may inject another, so
+ * inspect both the error and the backend `{ error: { code, message, details } }`
+ * envelope instead of relying on one class.
+ */
+export declare function classifyDeviceLeaseFailure(error: unknown): DeviceLeaseFailure;
 export declare function getDeviceNumber(businessId: string): string | null;
 export declare function isOnlineOnly(businessId: string): boolean;
 export declare function ensureLease(businessId: string): Promise<string | null>;

package/dist/sync/device-lease.service.js

@@ -10,6 +10,80 @@ import { getAppInstanceIdAsync } from "../adapters/devices";
 import { getConnectivityState } from "../adapters/connectivity";
 const LEASE_KEY = (businessId) => `teinc_device_number:${businessId}`;
 const LEASE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+const leaseFailures = new Map();
+export function getLastLeaseFailure(businessId) {
+    return leaseFailures.get(businessId) ?? null;
+}
+function rememberLeaseFailure(businessId, failure) {
+    leaseFailures.set(businessId, failure);
+}
+function clearLeaseFailure(businessId) {
+    leaseFailures.delete(businessId);
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Normalise the HTTP-client error into a user-presentable lease failure.
+ * Desktop injects its own ApiError shape; mobile/core may inject another, so
+ * inspect both the error and the backend `{ error: { code, message, details } }`
+ * envelope instead of relying on one class.
+ */
+export function classifyDeviceLeaseFailure(error) {
+    const e = (asRecord(error) ?? {});
+    const responseData = asRecord(e.data) ?? asRecord(e.response?.data);
+    const errorBody = asRecord(responseData?.error);
+    const details = asRecord(errorBody?.details);
+    const status = asNumber(e.status);
+    const code = typeof errorBody?.code === "string"
+        ? errorBody.code
+        : typeof e.code === "string"
+            ? e.code
+            : undefined;
+    const message = typeof errorBody?.message === "string"
+        ? errorBody.message
+        : typeof e.message === "string"
+            ? e.message
+            : "";
+    const limit = asNumber(details?.limit);
+    const current = asNumber(details?.current);
+    if (status === 402 || code === "TERMINAL_LIMIT_REACHED") {
+        return {
+            code: "TERMINAL_LIMIT_REACHED",
+            message: message ||
+                "This business has reached the number of linked terminals allowed by its plan.",
+            status,
+            limit,
+            current,
+        };
+    }
+    if (status === 429 || code === "DEVICE_LIMIT_REACHED") {
+        return {
+            code: "DEVICE_LIMIT_REACHED",
+            message: message || "This business has reached the maximum number of linked terminals.",
+            status,
+        };
+    }
+    if (status === 401 ||
+        message.includes("TOKEN_MISSING") ||
+        message.includes("No authentication token")) {
+        return {
+            code: "AUTH_REQUIRED",
+            message: message || "Sign-in is still finishing. Retry in a moment.",
+            status,
+        };
+    }
+    return {
+        code: "LEASE_FAILED",
+        message: message || "The terminal could not be activated.",
+        status,
+    };
+}
 export function getDeviceNumber(businessId) {
     const v = getSync(LEASE_KEY(businessId));
     if (v && /^(0[1-9]|[1-9][0-9])$/.test(v))
@@ -23,6 +97,7 @@ export async function ensureLease(businessId) {
     // Offline-first: keep leased DD even offline — if online check/lease fails, return cached
     const existingSync = getDeviceNumber(businessId);
     if (existingSync) {
+        clearLeaseFailure(businessId);
         // Opportunistically refresh touch if online, but never discard cached on failure
         if (getConnectivityState().isOnline) {
             try {
@@ -48,6 +123,7 @@ export async function ensureLease(businessId) {
                 setSync(LEASE_KEY(businessId), asyncCached);
             }
             catch { }
+            clearLeaseFailure(businessId);
             return asyncCached;
         }
     }
@@ -55,13 +131,18 @@ export async function ensureLease(businessId) {
     // No cached DD — must lease online. If offline, keep null (caller blocks POS with clear message)
     if (!getConnectivityState().isOnline) {
         syncLogger.debug("DeviceLease", "Offline and no cached DD — need online once", { businessId });
+        rememberLeaseFailure(businessId, {
+            code: "OFFLINE",
+            message: "Connect to the internet once so this terminal can be activated.",
+        });
         return null;
     }
     try {
         const http = getHttpClient();
         const deviceUuid = await getAppInstanceIdAsync();
         const res = await http.post(`/businesses/${businessId}/devices/lease`, { device_uuid: deviceUuid, app_instance_id: deviceUuid });
-        const data = res.data?.data ?? res.data;
+        const payload = res.data;
+        const data = payload.data ?? payload;
         const dn = data.device_number;
         if (dn && /^(0[1-9]|[1-9][0-9])$/.test(dn)) {
             setSync(LEASE_KEY(businessId), dn);
@@ -70,51 +151,57 @@ export async function ensureLease(businessId) {
                 await getItem(LEASE_KEY(businessId));
             }
             catch { }
+            clearLeaseFailure(businessId);
             syncLogger.info("DeviceLease", "Leased device number", { businessId, device_number: dn });
             return dn;
         }
+        rememberLeaseFailure(businessId, {
+            code: "LEASE_FAILED",
+            message: "The server did not return a terminal number. Try again.",
+        });
     }
     catch (e) {
-        const apiErr = e;
-        const msg = String(e?.message ?? "");
-        const isAuth = apiErr?.status === 401 || msg.includes("TOKEN_MISSING") || msg.includes("No authentication token");
-        if (isAuth) {
-            syncLogger.debug("DeviceLease", "No auth yet — lease deferred until login", { businessId });
-            // fallback to any async cache that may have appeared concurrently
-            try {
-                const fallback = await getItem(LEASE_KEY(businessId));
-                if (fallback && /^(0[1-9]|[1-9][0-9])$/.test(fallback))
-                    return fallback;
-            }
-            catch { }
-            const again = getDeviceNumber(businessId);
-            if (again)
-                return again;
-            return null;
+        const failure = classifyDeviceLeaseFailure(e);
+        rememberLeaseFailure(businessId, failure);
+        if (failure.code === "TERMINAL_LIMIT_REACHED" || failure.code === "DEVICE_LIMIT_REACHED") {
+            syncLogger.warn("DeviceLease", "Terminal limit reached — activation needs a free slot", {
+                businessId,
+                code: failure.code,
+                limit: failure.limit,
+                current: failure.current,
+            });
+            return cachedLeaseFallback(businessId);
         }
-        if (apiErr?.status === 429 || msg.includes("DEVICE_LIMIT_REACHED")) {
-            syncLogger.warn("DeviceLease", "Device limit reached — online only", { businessId });
-            return null;
+        if (failure.code === "AUTH_REQUIRED") {
+            syncLogger.debug("DeviceLease", "No auth yet — lease deferred until login", { businessId });
+            return cachedLeaseFallback(businessId);
         }
-        // Network/offline failure while leasing — keep any cached that may exist
+        // Network/offline failure while leasing — keep any cached that may exist.
         syncLogger.warn("DeviceLease", "Lease failed — keep cached if any", {
             businessId,
             error: String(e),
         });
-        try {
-            const fallback = await getItem(LEASE_KEY(businessId));
-            if (fallback && /^(0[1-9]|[1-9][0-9])$/.test(fallback)) {
-                try {
-                    setSync(LEASE_KEY(businessId), fallback);
-                }
-                catch { }
-                return fallback;
+        return cachedLeaseFallback(businessId);
+    }
+    return cachedLeaseFallback(businessId);
+}
+async function cachedLeaseFallback(businessId) {
+    try {
+        const fallback = await getItem(LEASE_KEY(businessId));
+        if (fallback && /^(0[1-9]|[1-9][0-9])$/.test(fallback)) {
+            try {
+                setSync(LEASE_KEY(businessId), fallback);
             }
+            catch { }
+            clearLeaseFailure(businessId);
+            return fallback;
         }
-        catch { }
-        const again = getDeviceNumber(businessId);
-        if (again)
-            return again;
+    }
+    catch { }
+    const again = getDeviceNumber(businessId);
+    if (again) {
+        clearLeaseFailure(businessId);
+        return again;
     }
     return null;
 }
@@ -141,6 +228,7 @@ export async function refreshLease(businessId) {
 export function clearLeaseForTests(businessId) {
     removeItemSync(LEASE_KEY(businessId));
     removeItemSync(`${LEASE_KEY(businessId)}:leased_at`);
+    clearLeaseFailure(businessId);
 }
 export const deviceLeaseService = {
     getDeviceNumber,

package/dist/sync/startup-readiness.d.ts

@@ -11,6 +11,8 @@
  *
  * Seller-only. Fleet/rider surfaces are fully online and never gate here.
  */
+import { type DeviceLeaseFailure } from "./device-lease.service";
+import { type ConnectivityState } from "../adapters/connectivity";
 import type { ReferenceDataKey } from "../reference/types";
 /**
  * Reference keys required before the app presents itself as ready to take
@@ -31,6 +33,13 @@ export interface StartupReadiness {
      * by itself block readiness.
      */
     entitlementUnverified: boolean;
+    /**
+     * Why the terminal lease failed, when `needsLease` is true. Lets the UI show
+     * "terminal limit reached" instead of the generic offline-data message.
+     */
+    leaseError: DeviceLeaseFailure | null;
+    /** Connectivity snapshot used for this check. */
+    network: ConnectivityState;
 }
 /** Evaluate the local cache only (no network). */
 export declare function getStartupReadiness(businessId: string): Promise<StartupReadiness>;

package/dist/sync/startup-readiness.js

@@ -15,7 +15,7 @@ import { openSyncDatabase } from "../db/connection";
 import { getReferenceData } from "../reference/operations";
 import { referenceSyncService } from "../reference/service";
 import { evaluateBusinessEntitlements } from "../reference/entitlement-guard";
-import { ensureLease } from "./device-lease.service";
+import { ensureLease, getLastLeaseFailure, } from "./device-lease.service";
 import { getConnectivityState } from "../adapters/connectivity";
 import { syncLogger } from "../utils/sync-logger";
 /**
@@ -52,6 +52,7 @@ export async function getStartupReadiness(businessId) {
         syncLogger.warn("StartupReadiness", "lease check failed", { err: String(e) });
     }
     const needsLease = !deviceNumber;
+    const leaseError = needsLease ? getLastLeaseFailure(businessId) : null;
     let entitlementUnverified = missingKeys.includes("subscription:entitlements");
     if (!entitlementUnverified) {
         try {
@@ -67,6 +68,8 @@ export async function getStartupReadiness(businessId) {
         missingKeys,
         needsLease,
         entitlementUnverified,
+        leaseError,
+        network: getConnectivityState(),
     };
 }
 /**

package/dist/sync/sync-jobs.service.js

@@ -217,7 +217,12 @@ async function tryRest(businessId, payload, commandType) {
                 const riderId = (payload.rider_id ?? payload.riderId);
                 if (!riderId)
                     return { ok: false, status: 422, code: "MISSING_RIDER", message: "Assign rider job has no rider_id — re-assign from the app" };
-                await http.post(`/deliveries/assign`, { order_id: orderId, rider_id: riderId });
+                const idempotencyKey = (payload.idempotency_key ?? payload.idempotencyKey);
+                await http.post(`/deliveries/assign`, {
+                    order_id: orderId,
+                    rider_id: riderId,
+                    ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
+                });
                 return { ok: true };
             }
             // POST /deliveries/:deliveryId/confirm-handover — resolve the delivery

package/dist/sync/transport-rest.js

@@ -84,7 +84,8 @@ export class RestTransport {
                 return this.executeOrderTransition(command, "cancel", timestamp, () => sellerService.cancelOrder(entity_id));
             }
             case "delivery:assign": {
-                const response = await kioskService.assignKioskOrderToRider(entity_id, payload.rider_id);
+                const assignPayload = payload;
+                const response = await kioskService.assignKioskOrderToRider(entity_id, assignPayload.rider_id, assignPayload.idempotency_key ?? command.command_id);
                 return this.wrapResponse("delivery.assigned", response, entity_id, timestamp, command);
             }
             case "delivery:confirm_handover": {

package/package.json

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