@teincfood/core 0.8.3 → 0.9.0

package/dist/sync/online-gates.js

@@ -7,8 +7,12 @@
  * ever fulfill them without the backend.
  */
 import { getConnectivityState } from "../adapters/connectivity";
+import { TRANSITION_ERROR_CODES, TransitionError } from "./transition-errors";
 /** Command types that require the cloud, unconditionally. */
 export const ONLINE_REQUIRED = {
+    "delivery:assign": "Assign rider requires online",
+    "delivery:confirm_handover": "Handover confirmation requires online",
+    // Aliases used by the domain/LAN action path (transitionLocalOrder).
     "order:assign_rider": "Assign rider requires online",
     "order:confirm_handover": "Handover confirmation requires online",
     "chat:send": "Chat requires online",
@@ -22,6 +26,8 @@ export const ONLINE_REQUIRED = {
     "wallet:payout": "Payouts require online",
     "payment:charge_online": "Online payment requires online",
     "device:lease": "Device lease requires online (first lease only)",
+    "subscription:manage": "Plan changes and checkout require online",
+    "subscription:checkout": "Plan checkout requires online",
 };
 export function isOnlineCapable() {
     const s = getConnectivityState();
@@ -36,20 +42,47 @@ export function assertOnlineFor(commandType, payload) {
     const fixed = ONLINE_REQUIRED[commandType];
     if (fixed) {
         if (!isOnlineCapable())
-            throw new Error(fixed);
+            throw new TransitionError(TRANSITION_ERROR_CODES.ONLINE_REQUIRED, fixed);
         return;
     }
     if (commandType === "order:create" && payload) {
         const orderType = payload.order_type;
         if (orderType === "delivery" || payload.delivery_params) {
             if (!isOnlineCapable())
-                throw new Error("Delivery orders require online");
+                throw new TransitionError(TRANSITION_ERROR_CODES.ONLINE_REQUIRED, "Delivery orders require online");
             return;
         }
         const method = payload.pos_payment_method;
         if (typeof method === "string" && method !== "cash") {
             if (!isOnlineCapable())
-                throw new Error("Online payment requires online — use cash while offline");
+                throw new TransitionError(TRANSITION_ERROR_CODES.ONLINE_REQUIRED, "Online payment requires online — use cash while offline");
         }
     }
 }
+/**
+ * Offline entitlement gate (fail-closed). Host apps evaluate the cached
+ * signed envelope via `evaluateEntitlements` and pass `entitled` here for
+ * gated commands (menu/member/promo/terminal/dispatch creation, online
+ * orders). Expired, stale (> max_offline_days), or unverified => throw.
+ * RBAC (`hasCapabilitySync`) stays fail-open (backend 403 backstop);
+ * entitlements are the opposite: no proof => no access.
+ */
+export function assertEntitledFor(commandType, entitled, evaluationReason) {
+    const gated = new Set([
+        "order:create_online",
+        "menu:create_item",
+        "menu:update_item",
+        "menu:delete_item",
+        "menu:create_category",
+        "promo:create",
+        "member:invite",
+        "member:manage",
+        "terminal:link",
+        "fleet:dispatch_create",
+    ]);
+    if (!gated.has(commandType))
+        return;
+    if (!entitled) {
+        throw new TransitionError(TRANSITION_ERROR_CODES.SUBSCRIPTION_REQUIRED, evaluationReason ?? "Subscription required — upgrade or reconnect to verify");
+    }
+}

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

@@ -33,8 +33,18 @@ declare class OrderSnapshotsService {
     /**
      * 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.
+     * Also applies delivery linkage (delivery.assigned / delivery.status_changed
+     * / delivery.pickup_confirmed): backend emits delivery events WITHOUT an
+     * order.status_changed for assign + merchant/rider single-confirms, so
+     * without this other terminals keep offering "Assign rider" forever.
      */
     private applyOrderStatusToReadModel;
+    private businessIdOf;
+    private orderIdOf;
+    /** delivery.assigned {order_id, rider_id}, entity = delivery id. */
+    private applyDeliveryAssignedToReadModel;
+    /** delivery.status_changed {order_id, status} / delivery.pickup_confirmed {order_id, rider_confirmed, merchant_confirmed, status}. */
+    private applyDeliveryStatusToReadModel;
     /**
      * Write through a fetched order list so it is available offline. Used by the
      * seller and POS order queries. `scope` distinguishes complementary lists

package/dist/sync/order-snapshots.service.js

@@ -145,9 +145,21 @@ class OrderSnapshotsService {
     /**
      * 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.
+     * Also applies delivery linkage (delivery.assigned / delivery.status_changed
+     * / delivery.pickup_confirmed): backend emits delivery events WITHOUT an
+     * order.status_changed for assign + merchant/rider single-confirms, so
+     * without this other terminals keep offering "Assign rider" forever.
      */
     async applyOrderStatusToReadModel(db, event) {
         const payload = event.payload;
+        if (event.event_type === "delivery.assigned") {
+            await this.applyDeliveryAssignedToReadModel(db, event);
+            return;
+        }
+        if (event.event_type === "delivery.status_changed" || event.event_type === "delivery.pickup_confirmed") {
+            await this.applyDeliveryStatusToReadModel(db, event);
+            return;
+        }
         const orderId = payload?.order_id;
         const toStatus = payload?.to_status ??
             payload?.status;
@@ -156,6 +168,90 @@ class OrderSnapshotsService {
         }
         await this.applyOrderStatusToReadModelInternal(db, orderId, toStatus, event);
     }
+    businessIdOf(event) {
+        const payload = event.payload;
+        return (payload?.business_id ??
+            payload?.businessId ??
+            null);
+    }
+    orderIdOf(event) {
+        const payload = event.payload;
+        return payload?.order_id ?? event.entity_id;
+    }
+    /** delivery.assigned {order_id, rider_id}, entity = delivery id. */
+    async applyDeliveryAssignedToReadModel(db, event) {
+        try {
+            const payload = event.payload;
+            const orderId = this.orderIdOf(event);
+            const businessId = this.businessIdOf(event);
+            const deliveryId = event.entity_id ?? payload?.delivery_id;
+            if (!orderId || !businessId || !deliveryId)
+                return;
+            try {
+                const { updateOrderDelivery } = await import("../db/operations");
+                await updateOrderDelivery(db, businessId, orderId, { delivery_id: deliveryId });
+            }
+            catch { }
+            const lists = await getEntitySnapshotsByType(db, "seller_orders", businessId);
+            for (const list of lists) {
+                const data = list.payload.data ?? [];
+                const idx = data.findIndex((o) => o.id === orderId);
+                if (idx === -1)
+                    continue;
+                const updated = data.map((o, i) => i === idx ? { ...o, delivery_id: deliveryId, delivery_status: "assigned" } : o);
+                await upsertEntitySnapshot(db, {
+                    entityType: "seller_orders",
+                    entityId: list.entity_id,
+                    businessId: list.business_id,
+                    lastEventId: event.event_id,
+                    lastEventTimestamp: event.timestamp,
+                    payload: { ...list.payload, data: updated },
+                });
+            }
+        }
+        catch (error) {
+            syncLogger.error("OrderSnapshots", "Failed to apply delivery.assigned to read model", { error: String(error) });
+        }
+    }
+    /** delivery.status_changed {order_id, status} / delivery.pickup_confirmed {order_id, rider_confirmed, merchant_confirmed, status}. */
+    async applyDeliveryStatusToReadModel(db, event) {
+        try {
+            const payload = event.payload;
+            const orderId = this.orderIdOf(event);
+            const businessId = this.businessIdOf(event);
+            if (!orderId || !businessId)
+                return;
+            const deliveryStatus = payload?.status;
+            const patch = {};
+            if (deliveryStatus)
+                patch.delivery_status = deliveryStatus;
+            if (typeof payload?.merchant_confirmed === "boolean")
+                patch.merchant_handover_confirmed_at = payload.merchant_confirmed ? event.timestamp : null;
+            if (typeof payload?.rider_confirmed === "boolean")
+                patch.rider_handover_confirmed_at = payload.rider_confirmed ? event.timestamp : null;
+            if (Object.keys(patch).length === 0)
+                return;
+            const lists = await getEntitySnapshotsByType(db, "seller_orders", businessId);
+            for (const list of lists) {
+                const data = list.payload.data ?? [];
+                const idx = data.findIndex((o) => o.id === orderId);
+                if (idx === -1)
+                    continue;
+                const updated = data.map((o, i) => (i === idx ? { ...o, ...patch } : o));
+                await upsertEntitySnapshot(db, {
+                    entityType: "seller_orders",
+                    entityId: list.entity_id,
+                    businessId: list.business_id,
+                    lastEventId: event.event_id,
+                    lastEventTimestamp: event.timestamp,
+                    payload: { ...list.payload, data: updated },
+                });
+            }
+        }
+        catch (error) {
+            syncLogger.error("OrderSnapshots", "Failed to apply delivery status to read model", { error: String(error) });
+        }
+    }
     /**
      * Write through a fetched order list so it is available offline. Used by the
      * seller and POS order queries. `scope` distinguishes complementary lists

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

@@ -15,7 +15,8 @@ import { recordAttempt } from "../utils/attempt-stats";
 import { BackoffTracker } from "./backoff";
 import { generateOrderNumber } from "./order-number";
 import { orderSnapshotsService } from "./order-snapshots.service";
-import { getTransitionPath } from "./transition-endpoints";
+import { getTransitionPath, DELIVERY_COMMANDS } from "./transition-endpoints";
+import { extractApiErrorCode } from "../utils/error";
 import { canBusinessSync, isAuthenticated } from "./sync-guard";
 const inflight = new Map();
 const retryTimers = new Map();
@@ -167,6 +168,33 @@ async function tryRest(businessId, payload, commandType) {
         const orderId = (payload.orderId ?? payload.order_id ?? payload.entity_id ?? payload.id);
         if (!orderId)
             return { ok: false, message: "missing orderId" };
+        if (DELIVERY_COMMANDS.has(commandType)) {
+            const db = await openSyncDatabase();
+            const isAssign = commandType === "delivery:assign" || commandType === "order:assign_rider";
+            if (isAssign) {
+                // POST /deliveries/assign {order_id, rider_id} — rider_id must have
+                // been captured at tap time; without it the job can never succeed.
+                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 });
+                return { ok: true };
+            }
+            // POST /deliveries/:deliveryId/confirm-handover — resolve the delivery
+            // id from the local order row (sync payloads carry the order id).
+            let deliveryId = payload.delivery_id;
+            if (!deliveryId) {
+                try {
+                    const row = await db.getFirstAsync(`SELECT delivery_id FROM orders WHERE business_id=? AND id=?;`, businessId, orderId);
+                    deliveryId = row?.delivery_id ?? undefined;
+                }
+                catch { }
+            }
+            if (!deliveryId)
+                return { ok: false, status: 422, code: "NO_DELIVERY", message: "Handover job has no delivery — rider not assigned yet" };
+            await http.post(`/deliveries/${deliveryId}/confirm-handover`, {});
+            return { ok: true };
+        }
         const path = getTransitionPath(commandType, orderId);
         if (!path)
             return { ok: false, message: `unknown command ${commandType}` };
@@ -176,7 +204,8 @@ async function tryRest(businessId, payload, commandType) {
     catch (e) {
         const err = e;
         const status = err.status ?? err.response?.status;
-        const bodyCode = err.response?.data?.error?.code;
+        // Backend code via every envelope shape (core ApiError, axios, app ApiError).
+        const bodyCode = extractApiErrorCode(e);
         const bodyMsg = err.response?.data?.error?.message;
         return {
             ok: false,
@@ -267,9 +296,9 @@ export async function drainOne(businessId, entityId) {
             catch { }
             return;
         }
-        // 3) Handle 409 RRR regen same UUID (POS create only)
+        // 3) Handle 409 RRR regen same UUID (POS create only, exact backend code)
         syncLogger.debug("SyncJobs", "check 409", { businessId, entityId, status: rest.status, code: rest.code });
-        const is409 = rest.status === 409 && (String(rest.code ?? "").includes("ORDER_NUMBER_TAKEN") || String(rest.message ?? "").includes("ORDER_NUMBER_TAKEN"));
+        const is409 = rest.status === 409 && rest.code === "ORDER_NUMBER_TAKEN";
         if (is409) {
             const on = (payload.order_number ?? payload.local_order_number);
             const parsed = on ? String(on).match(/^([0-9]{2})-([0-9]{3})-([0-9]{3})$/) : null;
@@ -329,10 +358,8 @@ export async function drainOne(businessId, entityId) {
         // 404 is only retryable for order:create (FIFO race: order not yet created
         // on backend). For transitions, 404 means the order was deleted or never
         // synced — permanent. 409 handled above for RRR regen. 401/408/429 need
-        // special handling below.
-        const codeUpper = String(rest.code ?? "").toUpperCase();
-        const msgUpper = String(rest.message ?? "").toUpperCase();
-        const isBusinessClosed = codeUpper.includes("BUSINESS_CLOSED") || msgUpper.includes("BUSINESS_CLOSED") || msgUpper.includes("BUSINESS IS CLOSED") || codeUpper.includes("HOURS_NOT_SYNCED");
+        // special handling below. Backend codes are exact (no message matching).
+        const isBusinessClosed = rest.code === "BUSINESS_CLOSED" || rest.code === "HOURS_NOT_SYNCED";
         const is4xx = rest.status && rest.status >= 400 && rest.status < 500;
         const isRetryable4xx = rest.status === 401 || rest.status === 408 || rest.status === 409 || rest.status === 429
             || (rest.status === 404 && row.command_type === "order:create")

package/dist/sync/transition-endpoints.d.ts

@@ -3,9 +3,17 @@
  *
  * Single source used by both the sync_jobs drain (tryRest) and the REST
  * transport (executeOrderTransition) so endpoint definitions cannot drift.
+ *
+ * Delivery commands do NOT live under /orders/:id — backend routes are
+ * POST /deliveries/assign {order_id, rider_id} and
+ * POST /deliveries/:deliveryId/confirm-handover. tryRest builds those
+ * bodies/paths (resolving delivery_id from SQLite when needed).
  */
+/** Command types fulfilled by the delivery endpoints (strictly online). */
+export declare const DELIVERY_COMMANDS: Set<string>;
 /**
  * Build the REST path for a given command type and order/delivery ID.
- * Returns null for unknown command types.
+ * Returns null for unknown command types AND for delivery commands, which
+ * need body/path resolution in tryRest (rider_id, delivery_id lookup).
  */
 export declare function getTransitionPath(commandType: string, entityId: string): string | null;

package/dist/sync/transition-endpoints.js

@@ -3,6 +3,11 @@
  *
  * Single source used by both the sync_jobs drain (tryRest) and the REST
  * transport (executeOrderTransition) so endpoint definitions cannot drift.
+ *
+ * Delivery commands do NOT live under /orders/:id — backend routes are
+ * POST /deliveries/assign {order_id, rider_id} and
+ * POST /deliveries/:deliveryId/confirm-handover. tryRest builds those
+ * bodies/paths (resolving delivery_id from SQLite when needed).
  */
 const ORDER_ENDPOINTS = {
     "order:accept": "accept",
@@ -13,16 +18,22 @@ const ORDER_ENDPOINTS = {
     "order:cancel": "cancel",
     "order:confirm_cash": "confirm-cash-payment",
     "order:pay": "confirm-cash-payment",
-    "order:assign_rider": "assign",
 };
+/** Command types fulfilled by the delivery endpoints (strictly online). */
+export const DELIVERY_COMMANDS = new Set([
+    "delivery:assign",
+    "delivery:confirm_handover",
+    "order:assign_rider",
+    "order:confirm_handover",
+]);
 /**
  * Build the REST path for a given command type and order/delivery ID.
- * Returns null for unknown command types.
+ * Returns null for unknown command types AND for delivery commands, which
+ * need body/path resolution in tryRest (rider_id, delivery_id lookup).
  */
 export function getTransitionPath(commandType, entityId) {
-    if (commandType === "order:confirm_handover") {
-        return `/deliveries/${entityId}/confirm-handover`;
-    }
+    if (DELIVERY_COMMANDS.has(commandType))
+        return null;
     const suffix = ORDER_ENDPOINTS[commandType];
     if (!suffix)
         return null;

package/dist/sync/transition-errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Coded errors for order/delivery transitions and sync control flow.
+ *
+ * Never branch on error message text: every backend action error carries a
+ * machine-readable `code` ({error: {code, message}}), and local guard
+ * rejections use the same codes below. Callers switch on `error.code`.
+ *
+ * Codes mirror the backend where semantics match (INVALID_TRANSITION,
+ * FORBIDDEN, ORDER_NOT_FOUND); client-only conditions use their own codes
+ * (ONLINE_REQUIRED, NO_ACTIVE_BUSINESS, SUBSCRIPTION_REQUIRED,
+ * REPLAY_DEFERRED, MISSING_RIDER, NO_DELIVERY).
+ */
+export declare const TRANSITION_ERROR_CODES: {
+    readonly INVALID_TRANSITION: "INVALID_TRANSITION";
+    readonly ONLINE_REQUIRED: "ONLINE_REQUIRED";
+    readonly NO_ACTIVE_BUSINESS: "NO_ACTIVE_BUSINESS";
+    readonly ORDER_NOT_FOUND: "ORDER_NOT_FOUND";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly SUBSCRIPTION_REQUIRED: "SUBSCRIPTION_REQUIRED";
+    readonly REPLAY_DEFERRED: "REPLAY_DEFERRED";
+    readonly MISSING_RIDER: "MISSING_RIDER";
+    readonly NO_DELIVERY: "NO_DELIVERY";
+};
+export type TransitionErrorCode = (typeof TRANSITION_ERROR_CODES)[keyof typeof TRANSITION_ERROR_CODES];
+export declare class TransitionError extends Error {
+    code: TransitionErrorCode | string;
+    constructor(code: TransitionErrorCode | string, message: string);
+}
+/** Read a machine-readable error code off any thrown value. */
+export declare function errorCodeOf(error: unknown): string | undefined;
+export declare function isFinalGuardRejection(error: unknown): boolean;
+export declare function isReplayDeferred(error: unknown): boolean;

package/dist/sync/transition-errors.js

@@ -0,0 +1,61 @@
+/**
+ * Coded errors for order/delivery transitions and sync control flow.
+ *
+ * Never branch on error message text: every backend action error carries a
+ * machine-readable `code` ({error: {code, message}}), and local guard
+ * rejections use the same codes below. Callers switch on `error.code`.
+ *
+ * Codes mirror the backend where semantics match (INVALID_TRANSITION,
+ * FORBIDDEN, ORDER_NOT_FOUND); client-only conditions use their own codes
+ * (ONLINE_REQUIRED, NO_ACTIVE_BUSINESS, SUBSCRIPTION_REQUIRED,
+ * REPLAY_DEFERRED, MISSING_RIDER, NO_DELIVERY).
+ */
+export const TRANSITION_ERROR_CODES = {
+    INVALID_TRANSITION: "INVALID_TRANSITION",
+    ONLINE_REQUIRED: "ONLINE_REQUIRED",
+    NO_ACTIVE_BUSINESS: "NO_ACTIVE_BUSINESS",
+    ORDER_NOT_FOUND: "ORDER_NOT_FOUND",
+    FORBIDDEN: "FORBIDDEN",
+    SUBSCRIPTION_REQUIRED: "SUBSCRIPTION_REQUIRED",
+    REPLAY_DEFERRED: "REPLAY_DEFERRED",
+    MISSING_RIDER: "MISSING_RIDER",
+    NO_DELIVERY: "NO_DELIVERY",
+};
+export class TransitionError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = "TransitionError";
+        this.code = code;
+    }
+}
+import { extractApiErrorCode } from "../utils/error";
+/** Read a machine-readable error code off any thrown value. */
+export function errorCodeOf(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const code = error.code;
+    if (typeof code === "string")
+        return code;
+    // Backend-shaped errors nested under response/data ({error: {code}}).
+    return extractApiErrorCode(error);
+}
+/**
+ * Guard rejections that must stand: the transport must surface them instead
+ * of POSTing past them (the complete-pickup 422 storm on delivery orders).
+ * ORDER_NOT_FOUND is intentionally excluded — the device may simply never
+ * have seen the order, in which case direct-REST fallback is correct.
+ */
+const FINAL_GUARD_CODES = new Set([
+    TRANSITION_ERROR_CODES.INVALID_TRANSITION,
+    TRANSITION_ERROR_CODES.ONLINE_REQUIRED,
+    TRANSITION_ERROR_CODES.NO_ACTIVE_BUSINESS,
+    TRANSITION_ERROR_CODES.FORBIDDEN,
+    TRANSITION_ERROR_CODES.SUBSCRIPTION_REQUIRED,
+]);
+export function isFinalGuardRejection(error) {
+    const code = errorCodeOf(error);
+    return code !== undefined && FINAL_GUARD_CODES.has(code);
+}
+export function isReplayDeferred(error) {
+    return errorCodeOf(error) === TRANSITION_ERROR_CODES.REPLAY_DEFERRED;
+}

package/dist/sync/transport-rest.d.ts

@@ -14,9 +14,11 @@ export declare class RestTransport implements Transport {
     private dispatchCommand;
     /**
      * Order transitions go through the domain service first (single write path:
-     * SQLite + sync_jobs). If this device never saw the order (e.g. a LAN node
-     * handling a cloud-created order before its first pull), fall back to the
-     * previous direct-REST behavior so availability never regresses.
+     * SQLite + sync_jobs). Direct-REST fallback is ONLY for devices that never
+     * saw the order (LAN node handling a cloud-created order before first pull).
+     * Local guard rejections (Cannot <action>, online-required, auth/business,
+     * capability) are rethrown — POSTing past them is what caused the
+     * complete-pickup 422 storm on delivery orders.
      */
     private executeOrderTransition;
     private wrapResponse;

package/dist/sync/transport-rest.js

@@ -9,6 +9,7 @@ import { sellerService, kioskService, menuService } from "../adapters/services";
 import { syncLogger } from "../utils/sync-logger";
 import { generateEventId } from "../utils/uuid";
 import { createLocalOrder, transitionLocalOrder } from "../domain/orders/service";
+import { isFinalGuardRejection } from "./transition-errors";
 import { openSyncDatabase } from "../db/connection";
 import { getOrderById, updateOrderStatus } from "../db/operations";
 export class RestTransport {
@@ -134,9 +135,11 @@ export class RestTransport {
     }
     /**
      * Order transitions go through the domain service first (single write path:
-     * SQLite + sync_jobs). If this device never saw the order (e.g. a LAN node
-     * handling a cloud-created order before its first pull), fall back to the
-     * previous direct-REST behavior so availability never regresses.
+     * SQLite + sync_jobs). Direct-REST fallback is ONLY for devices that never
+     * saw the order (LAN node handling a cloud-created order before first pull).
+     * Local guard rejections (Cannot <action>, online-required, auth/business,
+     * capability) are rethrown — POSTing past them is what caused the
+     * complete-pickup 422 storm on delivery orders.
      */
     async executeOrderTransition(command, action, timestamp, restFallback, eventType = "order.status_changed") {
         const { business_id, entity_id } = command;
@@ -146,6 +149,10 @@ export class RestTransport {
             return this.wrapResponse(eventType, data, order.id, timestamp, command);
         }
         catch (error) {
+            // Guard rejections (by code, never message text) must stand — never
+            // POST past them. Only ORDER_NOT_FOUND falls back to REST.
+            if (isFinalGuardRejection(error))
+                throw error;
             syncLogger.warn("RestTransport", "domain transition unavailable, REST fallback", {
                 command_type: command.command_type,
                 entity_id,

package/dist/utils/error.js

@@ -39,6 +39,9 @@ export function extractApiErrorCode(error) {
     if (!error || typeof error !== "object")
         return undefined;
     const err = error;
+    // Core ApiError / TransitionError carry code on top level.
+    if (typeof err.code === "string")
+        return err.code;
     const response = err.response;
     if (response?.data && typeof response.data === "object") {
         const data = response.data;

package/dist/utils/order-transitions.js

@@ -22,6 +22,8 @@ export const PIPELINE = ["pending", "accepted", "preparing", "ready", "delivered
 // ── Helpers ───────────────────────────────────────────────────────────────
 export function isUnpaid(order) {
     const o = order;
+    if (o.pos_payment_method === "cash")
+        return false;
     return !o.is_paid && !o.paid_at && !o.payment?.is_paid;
 }
 export function isCancellable(status) {
@@ -72,11 +74,27 @@ export function nextActionFor(order) {
     if (status === "preparing")
         return { label: "Mark ready", key: "mark_ready" };
     if (status === "ready") {
+        // Delivery orders can NEVER complete pickup: backend rejects with
+        // INVALID_TRANSITION ("Only self-pickup orders can be completed this way").
+        // Ready delivery without a rider → assign one (online-only); with a rider
+        // → merchant handover confirm (online-only). Walk-in only below.
+        if (isDeliveryOrder(order)) {
+            const hasDelivery = !!order.delivery_id;
+            if (hasDelivery)
+                return { label: "Handover to rider", key: "confirm_handover" };
+            return { label: "Assign rider", key: "assign_rider" };
+        }
         const orderType = order.order_type ?? null;
-        // dine_in walk-in → Complete, else Pickup (takeout or delivery handover gate handled via getAllowedActions)
+        // dine_in walk-in → Complete, else Pickup (takeout)
         const label = orderType === "dine_in" ? "Complete" : "Picked up";
         return { label, key: "complete_pickup" };
     }
+    if (status === "waiting_pickup" || status === "on_the_way") {
+        if (isDeliveryOrder(order)) {
+            return { label: "Handover to rider", key: "confirm_handover" };
+        }
+        return null;
+    }
     return null;
 }
 export function canTransition(order, action) {

package/package.json

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