@final-commerce/command-frame 0.5.0-preprod.6 → 0.5.0-preprod.9

package/dist/actions/get-refund-plan/mock.d.ts

@@ -10,5 +10,10 @@ import { GetRefundPlan } from './types';
  * `maxRefundable` as the full captured amount. Against real kaching those
  * numbers come from `order.refund[]` and the capture's `emv` JSON. Use this
  * only to shape UI in local/standalone mode — never to assert real capacity.
+ *
+ * `allocation` is likewise shape-only: the demo has no refund SELECTION state
+ * and no company cash-rounding setting, so it always describes a FULL refund
+ * with `rounding: 0` and no cash `payout`. Against real kaching the allocation
+ * tracks the live selection and carries the drawer snap.
  */
 export declare const mockGetRefundPlan: GetRefundPlan;

package/dist/actions/get-refund-plan/mock.js

@@ -10,6 +10,11 @@ import { MOCK_ORDERS } from '../../demo/database';
  * `maxRefundable` as the full captured amount. Against real kaching those
  * numbers come from `order.refund[]` and the capture's `emv` JSON. Use this
  * only to shape UI in local/standalone mode — never to assert real capacity.
+ *
+ * `allocation` is likewise shape-only: the demo has no refund SELECTION state
+ * and no company cash-rounding setting, so it always describes a FULL refund
+ * with `rounding: 0` and no cash `payout`. Against real kaching the allocation
+ * tracks the live selection and carries the drawer snap.
  */
 export const mockGetRefundPlan = async (params) => {
     console.log('[Mock] getRefundPlan called', params);
@@ -45,10 +50,28 @@ export const mockGetRefundPlan = async (params) => {
     });
     const totalCaptured = sources.reduce((sum, s) => sum + s.capturedAmount, 0);
     const nonRefundableLiability = order.summary?.nonRevenueTotal ?? 0;
+    // Full-refund legs: every source returns its whole capture (the demo's
+    // `maxRefundable`), which is exactly the shape a full selection produces.
+    const legs = sources
+        .filter((s) => s.maxRefundable > 0)
+        .map((s) => ({
+        transactionId: s.transactionId,
+        amount: s.maxRefundable,
+        paymentType: s.paymentType,
+        requiresGiftCardDestination: s.paymentType === 'redeem',
+    }));
+    const budget = legs.reduce((sum, l) => sum + l.amount, 0);
     return {
         success: true,
         orderId: order._id,
         sources,
+        allocation: {
+            budget,
+            // No cash rounding in the demo, so the goods value and the budget agree.
+            itemTotal: budget,
+            rounding: 0,
+            legs,
+        },
         // Demo: no prior refunds, so remaining = captured minus the non-revenue load.
         remainingRefundable: Math.max(0, totalCaptured - nonRefundableLiability),
         nonRefundableLiability,

package/dist/actions/get-refund-plan/types.d.ts

@@ -1,6 +1,29 @@
 export interface GetRefundPlanParams {
     /** Order to inspect; defaults to the active order. */
     orderId?: string;
+    /**
+     * The selection to allocate — the SAME array you will pass to
+     * `processPartialRefund({ items })`, so the plan you render and the refund
+     * you submit are computed from one input.
+     *
+     * A flow that owns its own refund UI holds the selection in its own state and
+     * never stages it on the POS, so without this there is nothing for the engine
+     * to allocate. Pass it here on every selection change to get the matching
+     * {@link RefundPlanAllocation} back. **Purely a read** — unlike
+     * `processPartialRefund`, this never stages the selection or touches POS
+     * state, so it is safe to call as the cashier ticks rows.
+     *
+     * Omit it to fall back to the selection already staged on the POS (what
+     * `selectAllRefundItems` sets) — the in-POS modal's path. Omitted with
+     * nothing staged, no `allocation` comes back.
+     */
+    items?: {
+        /** `internalId` / `variantId` for a product, `customSaleId`, cart-fee id, or tip `transactionId`. */
+        itemKey: string;
+        quantity: number;
+        /** Optional hint; inferred from the order when omitted. */
+        type?: 'product' | 'customSale' | 'fee' | 'tip';
+    }[];
 }
 export interface RefundPlanSource {
     transactionId: string;
@@ -17,10 +40,68 @@ export interface RefundPlanSource {
     /** For redeem sources: the card number from the payment entry's emv, when present. */
     cardNumber?: string;
 }
+/**
+ * One ready-to-submit refund leg. Pass these straight to
+ * `processPartialRefund({ openUI: false, legs })` — the amounts are the
+ * engine's own allocation and already satisfy its Σ-contract.
+ */
+export interface RefundPlanLeg {
+    /** `transactionId` of the source payment this leg draws from — join key to `sources`. */
+    transactionId: string;
+    /** Amount to return to this source (minor units). Submit VERBATIM; do not re-derive. */
+    amount: number;
+    /** `cash` / `card` / `redeem` / etc., copied from the source. */
+    paymentType: string;
+    /** True when the leg must carry a `giftCard` destination (a `redeem` source). */
+    requiresGiftCardDestination: boolean;
+    /**
+     * Cash legs only: what the drawer actually pays after the company's
+     * cash-rounding snap, and the signed delta from `amount`. Display it
+     * ("drawer pays 6.50 (+0.01 rounding)") — never apply the snap yourself,
+     * and never stage `payout.amount` as the leg (`amount` is the leg).
+     */
+    payout?: {
+        amount: number;
+        rounding: number;
+    };
+}
+/**
+ * The engine's own allocation of the CURRENT refund selection across the
+ * order's captures — what a flow renders and submits instead of computing a
+ * split of its own.
+ *
+ * Present when the call carries a selection: either `params.items` (a flow
+ * holding its own selection — the usual case) or a selection already staged on
+ * the POS for the active order (`selectAllRefundItems`). Omitted for a bare
+ * capacity read with neither.
+ */
+export interface RefundPlanAllocation {
+    /**
+     * What Σ `legs.amount` MUST equal — `min(itemTotal, Σ maxRefundable)`, which
+     * on a FULL selection is the captured total, not the goods value. Staging the
+     * goods value instead is rejected with `refund.legSumMismatch`.
+     */
+    budget: number;
+    /** Goods value of the selection (minor units). DISPLAY ONLY — never allocate against it. */
+    itemTotal: number;
+    /**
+     * `budget − itemTotal` — the sale's cash rounding, returned to the tender that
+     * took it. Non-zero only on a cash-rounded capture; the engine stamps it as
+     * refund residue at commit.
+     */
+    rounding: number;
+    /** One leg per source that receives money. Submit as `legs`, unchanged. */
+    legs: RefundPlanLeg[];
+}
 export interface GetRefundPlanResponse {
     success: boolean;
     orderId: string;
     sources: RefundPlanSource[];
+    /**
+     * Ready-to-submit allocation of the current selection. Present only when a
+     * refund selection exists on the active order. See {@link RefundPlanAllocation}.
+     */
+    allocation?: RefundPlanAllocation;
     /** Order-level remaining refundable (minor units) — non-revenue liability already excluded. */
     remainingRefundable: number;
     /** Non-refundable liability (gift-card loads etc., minor units). */

package/dist/actions/get-refund-plan/types.js

@@ -4,4 +4,10 @@
 // order-level math so flows can PRESENT accurate refund options without
 // re-deriving the numbers client-side (the mutating commands —
 // `processPartialRefund` / `redeemRefund` — re-validate at submit time).
+//
+// `allocation` closes the last gap: capacities alone still left a flow to work
+// out WHICH tender gets WHAT, and a flow that split the goods value across the
+// tenders shaved the sale's cash rounding off gift-card legs and was rejected
+// at submit. The engine now returns the legs it would accept — render them,
+// submit them unchanged, compute nothing.
 export {};

package/dist/index.d.ts

@@ -141,8 +141,8 @@ export type { CalculateRefundTotal, CalculateRefundTotalParams, CalculateRefundT
 export type { GetRemainingRefundableQuantities, GetRemainingRefundableQuantitiesParams, GetRemainingRefundableQuantitiesResponse, } from './actions/get-remaining-refundable-quantities/types';
 export type { ProcessPartialRefund, ProcessPartialRefundParams, ProcessPartialRefundResponse, } from './actions/process-partial-refund/types';
 export type { RedeemRefund, RedeemRefundParams, RedeemRefundResponse } from './actions/redeem-refund/types';
-export type { GetRefundPlan, GetRefundPlanParams, GetRefundPlanResponse, RefundPlanSource, } from './actions/get-refund-plan/types';
-export type { CheckPermission, CheckPermissionParams, CheckPermissionResponse, } from './actions/check-permission/types';
+export type { GetRefundPlan, GetRefundPlanParams, GetRefundPlanResponse, RefundPlanSource, RefundPlanAllocation, RefundPlanLeg, } from './actions/get-refund-plan/types';
+export type { CheckPermission, CheckPermissionParams, CheckPermissionResponse } from './actions/check-permission/types';
 export type { InitiateRefund, InitiateRefundParams, InitiateRefundResponse } from './actions/initiate-refund/types';
 export type { GetCurrentCart, GetCurrentCartResponse } from './actions/get-current-cart/types';
 export type { AddProductDiscount, AddProductDiscountParams, AddProductDiscountResponse, } from './actions/add-product-discount/types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@final-commerce/command-frame",
-  "version": "0.5.0-preprod.6",
+  "version": "0.5.0-preprod.9",
   "description": "Commands Frame library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",