@teincfood/core 0.10.18 → 0.10.20

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/offline/service.d.ts

@@ -34,12 +34,26 @@ export interface OfflineSessionState {
     keyId: string | null;
     members: OfflineMemberCredential[];
 }
+interface OfflineActivationBaseArgs {
+    businessId: string;
+    appInstanceId?: string;
+    platform?: string;
+    deviceName?: string;
+    osVersion?: string;
+    appVersion?: string;
+}
 /**
- * First-time activation. Generates the device keypair, registers the public
- * key, stores the signed license and enrolls the current member's PIN.
+ * Activate the terminal license without creating any member PIN. The backend
+ * activation also enrolls the signed-in user, but the quick-login PIN is a
+ * separate, optional local credential.
  */
-export declare function activateOfflineDevice(args: {
-    businessId: string;
+export declare function activateOfflineLicense(args: OfflineActivationBaseArgs): Promise<OfflineActivationResult>;
+/**
+ * First-time activation plus the optional local quick-login PIN. Kept as the
+ * mobile-compatible entry point; desktop can call activateOfflineLicense()
+ * first and set the PIN later.
+ */
+export declare function activateOfflineDevice(args: OfflineActivationBaseArgs & {
     member: {
         userId: string;
         fullName: string;
@@ -48,12 +62,23 @@ export declare function activateOfflineDevice(args: {
         capabilities: string[];
     };
     pin: string;
-    appInstanceId?: string;
-    platform?: string;
-    deviceName?: string;
-    osVersion?: string;
-    appVersion?: string;
 }): Promise<OfflineActivationResult>;
+/**
+ * Set or change the local 6-digit quick-login PIN. Existing PINs must be
+ * confirmed first; changing a PIN never requires the network.
+ */
+export declare function setOfflineMemberPin(args: {
+    businessId: string;
+    userId: string;
+    newPin: string;
+    currentPin?: string;
+    member?: {
+        fullName: string;
+        email?: string | null;
+        role: string;
+        capabilities: string[];
+    };
+}): Promise<OfflineMemberCredential>;
 /** Refresh the signed license while online using the normal access token. */
 export declare function refreshOfflineLicense(businessId: string): Promise<OfflineActivationResult>;
 /**

package/dist/offline/service.js

@@ -12,7 +12,7 @@ import { getConnectivityState } from "../adapters/connectivity";
 import { syncLogger } from "../utils/sync-logger";
 import { offlineRandomBytes } from "./random";
 import { base64UrlDecode, base64UrlEncode, canonicalDeviceChallenge, decodeLicensePayload, evaluateOfflineLicense, generateOfflineDeviceKeypair, loadAndVerifyOfflineLicense, newOfflineNonce, signDeviceChallenge, verifyOfflineLicense, } from "./license";
-import { clearOfflineDevice, createOfflineMemberCredential, getDevicePrivateKey, getOfflineMember, getStoredLicense, getStoredLicenseKeyId, getStoredLicensePublicKey, listOfflineMembers, markOfflineMemberLogin, removeOfflineMember, saveDevicePrivateKey, saveStoredLicense, saveStoredLicenseKeyId, saveStoredLicensePublicKey, verifyOfflineMemberPin, } from "./store";
+import { clearOfflineDevice, createOfflineMemberCredential, getDevicePrivateKey, getOfflineMember, getStoredLicense, getStoredLicenseKeyId, getStoredLicensePublicKey, listOfflineMembers, markOfflineMemberLogin, removeOfflineMember, saveDevicePrivateKey, saveStoredLicense, saveStoredLicenseKeyId, saveStoredLicensePublicKey, updateOfflineMemberPin, verifyOfflineMemberPin, } from "./store";
 function randomBytes(length) {
     return offlineRandomBytes(length);
 }
@@ -29,10 +29,11 @@ async function getPrivateKeyBytes() {
     }
 }
 /**
- * First-time activation. Generates the device keypair, registers the public
- * key, stores the signed license and enrolls the current member's PIN.
+ * Activate the terminal license without creating any member PIN. The backend
+ * activation also enrolls the signed-in user, but the quick-login PIN is a
+ * separate, optional local credential.
  */
-export async function activateOfflineDevice(args) {
+export async function activateOfflineLicense(args) {
     if (!getAuthToken())
         throw new Error("Sign in online before activating this device");
     const deviceId = args.appInstanceId ?? (await getAppInstanceIdAsync());
@@ -57,6 +58,15 @@ export async function activateOfflineDevice(args) {
     await saveStoredLicense(args.businessId, data.license);
     await saveStoredLicensePublicKey(args.businessId, data.public_key);
     await saveStoredLicenseKeyId(args.businessId, data.key_id);
+    return { ...data, payload: verified };
+}
+/**
+ * First-time activation plus the optional local quick-login PIN. Kept as the
+ * mobile-compatible entry point; desktop can call activateOfflineLicense()
+ * first and set the PIN later.
+ */
+export async function activateOfflineDevice(args) {
+    const result = await activateOfflineLicense(args);
     await createOfflineMemberCredential({
         businessId: args.businessId,
         userId: args.member.userId,
@@ -70,14 +80,51 @@ export async function activateOfflineDevice(args) {
     // the intent explicit and is idempotent.
     await enrollMemberOnDevice({
         businessId: args.businessId,
-        deviceId,
+        deviceId: args.appInstanceId,
         userId: args.member.userId,
     }).catch((error) => {
         syncLogger.warn("OfflineAuth", "Member enrollment call failed", {
             error: String(error),
         });
     });
-    return { ...data, payload: verified };
+    return result;
+}
+/**
+ * Set or change the local 6-digit quick-login PIN. Existing PINs must be
+ * confirmed first; changing a PIN never requires the network.
+ */
+export async function setOfflineMemberPin(args) {
+    if (!/^\d{6}$/.test(args.newPin)) {
+        throw new Error("Offline PIN must be exactly 6 digits");
+    }
+    const existing = await getOfflineMember(args.userId, args.businessId);
+    if (existing) {
+        if (existing.pin_hash) {
+            if (!args.currentPin) {
+                throw new Error("Enter your current 6-digit PIN");
+            }
+            const valid = await verifyOfflineMemberPin(args.userId, args.currentPin, args.businessId);
+            if (!valid)
+                throw new Error("Current PIN is incorrect");
+        }
+        await updateOfflineMemberPin(args.userId, args.businessId, args.newPin);
+        const updated = await getOfflineMember(args.userId, args.businessId);
+        if (!updated)
+            throw new Error("Could not update the offline PIN");
+        return updated;
+    }
+    if (!args.member) {
+        throw new Error("Sign in online once before setting up an offline PIN");
+    }
+    return createOfflineMemberCredential({
+        businessId: args.businessId,
+        userId: args.userId,
+        fullName: args.member.fullName,
+        email: args.member.email,
+        role: args.member.role,
+        capabilities: args.member.capabilities,
+        pin: args.newPin,
+    });
 }
 /** Refresh the signed license while online using the normal access token. */
 export async function refreshOfflineLicense(businessId) {

package/dist/offline/store.d.ts

@@ -70,6 +70,8 @@ export declare function createOfflineMemberCredential(args: {
     capabilities: string[];
     pin: string;
 }): Promise<OfflineMemberCredential>;
+/** Replace an existing member's PIN without changing their role/capabilities. */
+export declare function updateOfflineMemberPin(userId: string, businessId: string, pin: string): Promise<void>;
 export declare const OFFLINE_PIN_MAX_ATTEMPTS = 5;
 export interface OfflinePinLockState {
     failedAttempts: number;

package/dist/offline/store.js

@@ -201,6 +201,23 @@ export async function createOfflineMemberCredential(args) {
     await saveOfflineMember(member);
     return member;
 }
+/** Replace an existing member's PIN without changing their role/capabilities. */
+export async function updateOfflineMemberPin(userId, businessId, pin) {
+    if (!/^\d{6}$/.test(pin)) {
+        throw new Error("Offline PIN must be exactly 6 digits");
+    }
+    const member = await getOfflineMember(userId, businessId);
+    if (!member)
+        throw new Error("This member has no offline credential on this device");
+    const salt = randomHex(32);
+    await saveOfflineMember({
+        ...member,
+        pin_salt: salt,
+        pin_hash: await hashPin(pin, salt),
+        failed_attempts: 0,
+        locked_until: null,
+    });
+}
 export const OFFLINE_PIN_MAX_ATTEMPTS = 5;
 export async function getOfflinePinLockState(userId, businessId) {
     const member = await getOfflineMember(userId, businessId);

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@teincfood/core",
-  "version": "0.10.18",
-  "description": "TeincFood shared offline-first core \u2014 types, sync engine, local DB, reference data, and repositories for mobile + desktop",
+  "version": "0.10.20",
+  "description": "TeincFood shared offline-first core — types, sync engine, local DB, reference data, and repositories for mobile + desktop",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",