@final-commerce/command-frame 0.11.1-preprod.2 → 0.11.1-preprod.5

package/dist/actions/assign-order-user/mock.js

@@ -1,3 +1,4 @@
+import { applyAssignment } from '@final-commerce/common';
 import { MOCK_ORDERS, MOCK_PARKED_ORDERS, MOCK_USERS, mockPublishEvent } from '../../demo/database';
 export const mockAssignOrderUser = async (params) => {
     console.log('[Mock] assignOrderUser called', params);
@@ -11,20 +12,19 @@ export const mockAssignOrderUser = async (params) => {
     if (!order) {
         throw new Error(`Order with ID ${params.orderId} not found`);
     }
-    if (params.userId === null) {
-        order.assignedUser = null;
-    }
-    else if (order.assignedUser?.userId !== params.userId) {
-        if (!MOCK_USERS.some((u) => u.id === params.userId)) {
-            throw new Error(`User with ID ${params.userId} not found`);
-        }
-        order.assignedUser = { userId: params.userId, assignedAt: new Date().toISOString() };
+    if (params.userId !== null && !MOCK_USERS.some((u) => u.id === params.userId)) {
+        throw new Error(`User with ID ${params.userId} not found`);
     }
+    order.assignedUser = applyAssignment(order, {
+        userId: params.userId,
+        label: params.label,
+        at: new Date().toISOString(),
+    });
     mockPublishEvent('orders', 'order-updated', { order });
     return {
         success: true,
         orderId: order._id,
-        assignedUser: order.assignedUser ?? null,
+        assignedUser: order.assignedUser,
         timestamp: new Date().toISOString(),
     };
 };

package/dist/actions/assign-order-user/types.d.ts

@@ -2,14 +2,25 @@ import type { CFOrderAssignedUser } from '../../CommonTypes';
 export interface AssignOrderUserParams {
     /** Order to assign. Omit to target the live cart's order — it must already exist (parked, paid or transitioned). */
     orderId?: string;
-    /** User to assign (e.g. the driver), or null to unassign. Replaces any current assignee. */
+    /**
+     * User to assign (e.g. the driver), or null to unassign. Assigning replaces the current
+     * assignee with the same `label`; the replaced one stays in the order's record, ended.
+     */
     userId: string | null;
+    /**
+     * Why the user is assigned, free text — e.g. 'delivery'. Omit for an unlabeled assignment.
+     * When unassigning, ends only this label's assignee; omit it to end every current assignment.
+     */
+    label?: string | null;
 }
 export interface AssignOrderUserResponse {
     success: boolean;
     orderId: string;
-    /** The order's assignee after the call; null when unassigned. */
-    assignedUser: CFOrderAssignedUser | null;
+    /**
+     * Everyone who has had the order after the call, oldest first. Entries without
+     * `unassignedAt` are the current assignees.
+     */
+    assignedUser: CFOrderAssignedUser[];
     timestamp: string;
 }
 export type AssignOrderUser = (params: AssignOrderUserParams) => Promise<AssignOrderUserResponse>;

package/dist/actions/get-orders/mock.js

@@ -1,3 +1,4 @@
+import { currentAssignees } from '@final-commerce/common';
 import { MOCK_ORDERS, MOCK_PARKED_ORDERS, MOCK_USERS, MOCK_STATIONS, MOCK_OUTLETS, safeSerialize, } from '../../demo/database';
 export const mockGetOrders = async (params) => {
     console.log('[Mock] getOrders called', params);
@@ -5,7 +6,7 @@ export const mockGetOrders = async (params) => {
     let orders = safeSerialize([...MOCK_ORDERS, ...MOCK_PARKED_ORDERS]);
     // Filter simulation
     if (params) {
-        const { customerId, status, sessionId, paymentState, fulfillmentState, outletId, assignedUserId, inCart, orderType, customStatusId, customStatusKey, scheduled, scheduledFrom, scheduledTo, searchValue, limit, offset, sortBy, sortDirection, } = params;
+        const { customerId, status, sessionId, paymentState, fulfillmentState, outletId, assignedUserId, assignedUserLabel, inCart, orderType, customStatusId, customStatusKey, scheduled, scheduledFrom, scheduledTo, searchValue, limit, offset, sortBy, sortDirection, } = params;
         // 1. Filtering
         if (customerId) {
             orders = orders.filter((o) => o.customer && '_id' in o.customer && o.customer._id === customerId);
@@ -27,11 +28,13 @@ export const mockGetOrders = async (params) => {
         if (outletId) {
             orders = orders.filter((o) => o.posData?.outlet === outletId);
         }
-        if (assignedUserId) {
-            orders = orders.filter((o) => o.assignedUser?.userId === assignedUserId);
-        }
-        else if (assignedUserId === null) {
-            orders = orders.filter((o) => o.assignedUser == null);
+        if (assignedUserId || assignedUserId === null || assignedUserLabel !== undefined) {
+            orders = orders.filter((o) => {
+                const holders = currentAssignees(o, assignedUserLabel);
+                if (assignedUserId === null)
+                    return holders.length === 0;
+                return assignedUserId ? holders.some((a) => a.userId === assignedUserId) : holders.length > 0;
+            });
         }
         if (orderType !== undefined) {
             const types = Array.isArray(orderType) ? orderType : [orderType];

package/dist/actions/get-orders/types.d.ts

@@ -11,10 +11,16 @@ export interface GetOrdersParams {
     /** Only orders placed at this outlet (`posData.outlet`). Without it, orders from every outlet in the company are returned. */
     outletId?: string;
     /**
-     * Only orders assigned to this user (`assignedUser.userId`), e.g. a driver's deliveries.
-     * `null`: only orders nobody is assigned to yet (e.g. deliveries awaiting a driver).
+     * Only orders this user is assigned to now (a current `assignedUser` entry), e.g. a driver's deliveries.
+     * `null`: only orders nobody is assigned to now (e.g. deliveries awaiting a driver).
      */
     assignedUserId?: string | null;
+    /**
+     * Narrows the assignee test to assignments with this label, e.g. 'delivery': with `assignedUserId`, that
+     * user must hold the order under this label; with `assignedUserId: null`, nobody holds it under this label;
+     * alone, someone holds it under this label. `null` means unlabeled assignments.
+     */
+    assignedUserLabel?: string | null;
     /**
      * true: only orders loaded in a cart; false: only orders that aren't. Reads `order.inCart` when the order
      * carries it, otherwise the legacy reading (fulfillment 'draft' / status 'in-cart').

package/dist/actions/record-external-payment/mock.js

@@ -19,11 +19,16 @@ export const mockRecordExternalPayment = async (params) => {
     if (amount > balanceDue) {
         throw new Error(`recordExternalPayment: amount ${amount} exceeds the balance due ${balanceDue}`);
     }
+    const tip = params.tip?.amount ?? 0;
+    if (params.tip !== undefined && (!Number.isInteger(tip) || tip <= 0)) {
+        throw new Error('recordExternalPayment: tip.amount must be a positive integer (minor units)');
+    }
     const order = applyMockPayment(amount, 'external', label);
     const remainingBalance = MOCK_CART.remainingBalance ?? 0;
     return {
         success: true,
         amount,
+        tip,
         label,
         paymentType: 'external',
         change: 0,

package/dist/actions/record-external-payment/types.d.ts

@@ -1,4 +1,11 @@
 import { CFOrder } from '../../CommonTypes';
+/** A tip the customer already paid wherever the money was taken (the website, a delivery app). */
+export interface RecordExternalPaymentTip {
+    /** Tip in integer MINOR currency units. Must be positive. */
+    amount: number;
+    /** User id the tip belongs to. Defaults to the cashier recording the payment. */
+    tipTo?: string;
+}
 export interface RecordExternalPaymentParams {
     /**
      * What the payment was — shown on the order and in reports, e.g. 'Paid online',
@@ -12,13 +19,21 @@ export interface RecordExternalPaymentParams {
      * the rest can be taken with any other tender. Above the balance due is an error.
      */
     amount?: number;
+    /**
+     * Tip paid along with it. Recorded ON TOP of `amount` — it never counts toward the
+     * balance due — and stored on the payment like a card tip, so reports and tip-outs
+     * see it. Omit for no tip.
+     */
+    tip?: RecordExternalPaymentTip;
     /** Fulfillment state to land on after full payment, e.g. 'pending' to keep the order going to the kitchen. */
     checkoutFulfillmentTarget?: string;
 }
 export interface RecordExternalPaymentResponse {
     success: boolean;
-    /** The amount recorded, in integer MINOR currency units. */
+    /** The amount recorded against the balance, in integer MINOR currency units. Excludes the tip. */
     amount: number;
+    /** The tip recorded on top of `amount`, in integer MINOR currency units; 0 when none. */
+    tip: number;
     /** The label, as recorded. */
     label: string;
     paymentType: 'external';

package/dist/index.d.ts

@@ -223,7 +223,7 @@ export type { GetOrderStatuses, GetOrderStatusesResponse } from './actions/get-o
 export type { DeleteParkedOrder, DeleteParkedOrderParams, DeleteParkedOrderResponse, } from './actions/delete-parked-order/types';
 export type { VoidOrder, VoidOrderParams, VoidOrderResponse, VoidOrderOutcome } from './actions/void-order/types';
 export type { CashPayment, CashPaymentParams, CashPaymentResponse } from './actions/cash-payment/types';
-export type { RecordExternalPayment, RecordExternalPaymentParams, RecordExternalPaymentResponse, } from './actions/record-external-payment/types';
+export type { RecordExternalPayment, RecordExternalPaymentParams, RecordExternalPaymentResponse, RecordExternalPaymentTip, } from './actions/record-external-payment/types';
 export type { GetCashRoundingAmount, GetCashRoundingAmountParams, GetCashRoundingAmountResponse, } from './actions/get-cash-rounding-amount/types';
 export type { TapToPayPayment, TapToPayPaymentParams, TapToPayPaymentResponse, } from './actions/tap-to-pay-payment/types';
 export type { TerminalPayment, TerminalPaymentParams, TerminalPaymentResponse } from './actions/terminal-payment/types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@final-commerce/command-frame",
-  "version": "0.11.1-preprod.2",
+  "version": "0.11.1-preprod.5",
   "description": "Commands Frame library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -57,7 +57,7 @@
     "ignoreBranchesMissingTickets": true
   },
   "dependencies": {
-    "@final-commerce/common": "2.8.1-preprod.1"
+    "@final-commerce/common": "2.8.1-preprod.3"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.0.0",