@final-commerce/command-frame 0.5.0-preprod.1 → 0.5.0-preprod.10

package/dist/actions/calculate-refund-total/action.js

@@ -3,6 +3,6 @@
  * Calls the calculateRefundTotal action on the parent window
  */
 import { commandFrameClient } from "../../client";
-export const calculateRefundTotal = async () => {
-    return await commandFrameClient.call("calculateRefundTotal");
+export const calculateRefundTotal = async (params) => {
+    return await commandFrameClient.call("calculateRefundTotal", params);
 };

package/dist/actions/can-transition/types.d.ts

@@ -1,6 +1,6 @@
 import type { CFStatePair, CFTransitionResult } from "../../common-types/order-state";
 export interface CanTransitionParams {
-    /** Order to evaluate. If omitted, evaluates against a new order (from = null). */
+    /** Order to evaluate. Defaults to the active order; if there is no active order (or none matches), evaluates as a brand-new order (from = null). */
     orderId?: string;
     /** Target state pair to transition to. */
     to: CFStatePair;

package/dist/actions/cash-payment/types.d.ts

@@ -3,14 +3,17 @@ export interface CashPaymentParams {
     /**
      * The amount to pay with this tender, in integer MINOR currency units
      * (e.g. 1575 = $15.75 — see `getContext().minorUnits` for the currency's
-     * exponent). Required. Semantics against the cart's balance due:
-     *   - missing            → error
+     * exponent). Required whenever the balance due is greater than $0; may be
+     * omitted only on a cart that already nets to a $0 balance due (e.g. fully
+     * discounted), where it defaults to 0. Semantics against the cart's
+     * balance due:
+     *   - missing            → error, unless the balance due is $0 (→ 0)
      *   - less than balance  → partial payment (the POS enters a fixed
      *                          split-payment leg for this amount)
      *   - equal to balance   → full payment
      *   - more than balance  → error (overpayment is `tenderedAmount`'s job)
      */
-    amount: number;
+    amount?: number;
     /**
      * Cash physically handed over by the customer, in integer MINOR currency
      * units. When provided, the POS computes the change itself (after applying

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,29 @@ 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,
+        requiresDestination: s.paymentType === 'redeem',
+        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,79 @@ 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 destination tender (a `redeem` source
+     * cannot be refunded to itself — the money needs somewhere to land, credited
+     * by the flow FIRST). The destination is usually a gift card but redeem is
+     * the general rail: loyalty and store-credit extensions ride it too.
+     */
+    requiresDestination: boolean;
+    /**
+     * @deprecated Same value as {@link RefundPlanLeg.requiresDestination} — the
+     * old name baked one extension (gift card) into a general redeem concept.
+     * Kept populated for existing callers; prefer `requiresDestination`.
+     */
+    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/actions/get-refunds/types.d.ts

@@ -3,7 +3,7 @@ export interface GetRefundsParams {
     orderId?: string;
     sessionId?: string;
     outletId?: string;
-    /** Default: 50. */
+    /** No default — when omitted, all matching refunds are returned. */
     limit?: number;
     /** Default: 0. */
     offset?: number;

package/dist/actions/get-remaining-refundable-quantities/action.js

@@ -3,6 +3,6 @@
  * Calls the getRemainingRefundableQuantities action on the parent window
  */
 import { commandFrameClient } from "../../client";
-export const getRemainingRefundableQuantities = async () => {
-    return await commandFrameClient.call("getRemainingRefundableQuantities");
+export const getRemainingRefundableQuantities = async (params) => {
+    return await commandFrameClient.call("getRemainingRefundableQuantities", params);
 };

package/dist/actions/get-remaining-refundable-quantities/mock.js

@@ -4,6 +4,8 @@ export const mockGetRemainingRefundableQuantities = async (_params) => {
         success: true,
         lineItems: {},
         customSales: {},
+        cartFees: {},
+        tips: {},
         timestamp: new Date().toISOString()
     };
 };

package/dist/actions/get-remaining-refundable-quantities/types.d.ts

@@ -5,6 +5,19 @@ export interface GetRemainingRefundableQuantitiesResponse {
     success: boolean;
     lineItems: Record<string, number>;
     customSales: Record<string, number>;
+    /**
+     * Remaining refundable cart fees, keyed by `order.cartFees[].id` —
+     * the same key `processPartialRefund` takes for `type: 'fee'` items.
+     * 0/1 semantics: `1` = still refundable, `0` = already refunded.
+     */
+    cartFees: Record<string, number>;
+    /**
+     * Remaining refundable tips, keyed by the paying method's
+     * `transactionId` — the same key `processPartialRefund` takes for
+     * `type: 'tip'` items. Only payment methods that carry a tip appear.
+     * 0/1 semantics: `1` = still refundable, `0` = already refunded.
+     */
+    tips: Record<string, number>;
     timestamp: string;
 }
 export type GetRemainingRefundableQuantities = (params?: GetRemainingRefundableQuantitiesParams) => Promise<GetRemainingRefundableQuantitiesResponse>;

package/dist/actions/initiate-refund/types.d.ts

@@ -7,4 +7,10 @@ export interface InitiateRefundResponse {
     orderId: string;
     timestamp: string;
 }
+/**
+ * @deprecated The host-side refund popup is disabled — no UI opens. Stages the
+ * active order (and arms barcode refund-scan routing when no `orderId` is
+ * given). Build refund UI in the flow: `getRefundPlan`,
+ * `getRemainingRefundableQuantities`, `processPartialRefund`, `redeemRefund`.
+ */
 export type InitiateRefund = (params?: InitiateRefundParams) => Promise<InitiateRefundResponse>;

package/dist/actions/process-partial-refund/mock.d.ts

@@ -1,2 +1,2 @@
-import { ProcessPartialRefund } from "./types";
+import { ProcessPartialRefund } from './types';
 export declare const mockProcessPartialRefund: ProcessPartialRefund;

package/dist/actions/process-partial-refund/mock.js

@@ -1,16 +1,25 @@
 export const mockProcessPartialRefund = async (params) => {
     // The mock has no split-payment modal or order engine, so `openUI` (default
-    // true on the real command), `legs` (the headless per-tender allocation) and
-    // any per-leg `giftCard` destination (mixed returns) are inert here — the
-    // shape is accepted and echoed, nothing else. No gift card is credited.
-    console.log("[Mock] processPartialRefund called", {
+    // true on the real command), `legs` (the headless per-tender allocation), a
+    // per-leg `giftCard` destination (mixed returns) and the top-level `giftCard`
+    // routing are all inert here — the shape is accepted and echoed, nothing
+    // else. No gift card is credited.
+    //
+    // The one rule worth mirroring is the mutual exclusion, so a flow built
+    // against the mock fails the same way it will against the runtime.
+    if (params?.legs && params?.giftCard) {
+        throw new Error('refund.giftCardAndLegs: pass either `legs` (you allocate) or `giftCard` (the engine allocates), not both');
+    }
+    console.log('[Mock] processPartialRefund called', {
         ...params,
         openUI: params?.openUI ?? true,
         legs: params?.legs ?? null,
+        giftCard: params?.giftCard ?? null,
     });
     return {
         success: true,
         refundId: 'mock_refund_' + Date.now(),
-        timestamp: new Date().toISOString()
+        modalRaised: false,
+        timestamp: new Date().toISOString(),
     };
 };

package/dist/actions/process-partial-refund/types.d.ts

@@ -2,10 +2,11 @@ export interface ProcessPartialRefundParams {
     /**
      * Optional refund reason.
      *
-     * KNOWN LIMITATION: not currently persisted on the `Refund` doc or the
-     * state-event audit row via this command — the runtime falls back to a
-     * fixed 'partial-refund' label instead. Unlike `redeemRefund`, whose
-     * `reason` IS recorded. See the README's "Known limitation" section.
+     * Recorded verbatim on the persisted `Refund` doc's `reason` field and on
+     * the state-event audit row — same as `redeemRefund`. When omitted, the
+     * refund doc's `reason` stays unset and only the audit row carries the
+     * 'partial-refund' fallback label. See the README's "`reason` persistence"
+     * section.
      */
     reason?: string;
     /** Optional: specify which order to refund (sets it as active). */
@@ -87,6 +88,47 @@ export interface ProcessPartialRefundParams {
             label?: string;
         };
     }[];
+    /**
+     * Route part (or all) of the refund onto ONE gift-card / store-credit tender
+     * and let the engine send whatever is left back to the original payments.
+     *
+     * This is the declarative alternative to hand-building `legs`: state the card
+     * and how much lands on it, and the engine does the allocation — it already
+     * owns that math for every other refund path. Prefer it over `legs` for a
+     * gift-card destination; a flow that computes its own split is duplicating
+     * engine arithmetic that will drift (see "Query, never recompute").
+     *
+     * - `amount` omitted → the WHOLE refund lands on the card (what an
+     *   all-`giftCard` `legs` staging does today).
+     * - `amount` set → that much lands on the card, in minor units; the
+     *   remainder returns to the original payments, allocated by the engine.
+     *
+     * DRAWING ORDER — the card is filled from the tenders that cannot be
+     * refunded to source first (a redeem tender has nowhere to return to), then
+     * proportionally from the rest. So `amount` can never be lower than what
+     * those tenders must contribute: below that the call throws
+     * `REFUND_GIFT_AMOUNT_BELOW_MINIMUM`, naming the minimum, and nothing is
+     * committed. Surface that message — it is the number to clamp the field to,
+     * so the flow never has to derive it.
+     *
+     * Exactly one destination card, therefore exactly ONE credit for the caller
+     * to place and one to reverse. **Credit-first:** credit `referenceId` for
+     * `amount` (or the full refund total when omitted) BEFORE calling; on any
+     * throw nothing was recorded — reverse it.
+     *
+     * Requires `openUI: false`. Mutually exclusive with `legs` — passing both
+     * throws, since they are two answers to the same question.
+     */
+    giftCard?: {
+        /** Card/account id the flow already credited (stored raw). */
+        referenceId: string;
+        /** Minor units landing on the card. Omit for the whole refund. */
+        amount?: number;
+        /** Provider/program name. Defaults to `giftCard`. */
+        processor?: string;
+        /** Human label for the destination tender. */
+        label?: string;
+    };
     /** Optional items to refund. */
     items?: {
         /** internalId or variantId or customSaleId. */
@@ -111,7 +153,25 @@ export interface ProcessPartialRefundParams {
 }
 export interface ProcessPartialRefundResponse {
     success: boolean;
-    refundId: string;
+    /**
+     * The persisted Refund document's id — the REAL one, usable to look the
+     * refund up. `null` means nothing has committed: the split-payment modal
+     * was raised (`modalRaised: true`) and owns the commit from there.
+     *
+     * Before kaching 1.9.5-preprod.17 this was the hardcoded string
+     * `'processed'` regardless of outcome, so a truthiness check could not
+     * detect a refund that silently didn't happen. Guard on it now:
+     * `if (!res.refundId && !res.modalRaised) …` is unreachable (such paths
+     * throw instead), so `res.refundId` alone answers "did money move".
+     */
+    refundId: string | null;
+    /**
+     * True when a multi-tender order raised the split-payment refund modal
+     * (`openUI` omitted or `true`): the cashier allocates there and the modal
+     * drives the commit — this call wrote nothing. Headless calls
+     * (`openUI: false`) never raise it.
+     */
+    modalRaised: boolean;
     timestamp: string;
 }
 export type ProcessPartialRefund = (params?: ProcessPartialRefundParams) => Promise<ProcessPartialRefundResponse>;

package/dist/actions/remove-product-fee/types.d.ts

@@ -1,10 +1,19 @@
 export interface RemoveProductFeeParams {
-    /** If provided, removes fee from specific cart item. Otherwise uses active product. */
+    /** If provided, removes fee(s) from a specific cart item. Otherwise uses active product. */
     internalId?: string;
+    /**
+     * 0-based index of the single fee to remove, in the order the line's fees
+     * were added (fees STACK — `addProductFee` appends). Omit to clear ALL
+     * fees on the line (the legacy behavior). Out-of-range indexes are a
+     * no-op.
+     */
+    index?: number;
 }
 export interface RemoveProductFeeResponse {
     success: boolean;
     internalId?: string;
+    /** Echoed when a single fee was targeted. */
+    index?: number;
     timestamp: string;
 }
 export type RemoveProductFee = (params?: RemoveProductFeeParams) => Promise<RemoveProductFeeResponse>;

package/dist/actions/select-all-refund-items/action.js

@@ -3,6 +3,6 @@
  * Calls the selectAllRefundItems action on the parent window
  */
 import { commandFrameClient } from "../../client";
-export const selectAllRefundItems = async () => {
-    return await commandFrameClient.call("selectAllRefundItems");
+export const selectAllRefundItems = async (params) => {
+    return await commandFrameClient.call("selectAllRefundItems", params);
 };

package/dist/actions/set-active-refund/types.d.ts

@@ -7,4 +7,4 @@ export interface SetActiveRefundResponse {
     refund: CFActiveRefundDetails;
     timestamp: string;
 }
-export type SetActiveRefund = (params?: SetActiveRefundParams) => Promise<SetActiveRefundResponse>;
+export type SetActiveRefund = (params: SetActiveRefundParams) => Promise<SetActiveRefundResponse>;

package/dist/actions/set-refund-stock-action/types.d.ts

@@ -1,6 +1,6 @@
 export interface SetRefundStockActionParams {
     orderId?: string;
-    /** The 'key' field from getLineItemsByOrder response (internalId || variantId || productId). */
+    /** The 'key' field from getLineItemsByOrder response (internalId, falling back to variantId). */
     itemKey: string;
     action: 'RESTOCK' | 'REFUND_DAMAGE';
 }

package/dist/actions/tap-to-pay-payment/types.d.ts

@@ -2,14 +2,17 @@ import { CFOrder } from "../../CommonTypes";
 export interface TapToPayPaymentParams {
     /**
      * The amount to pay with this tender, in integer MINOR currency units
-     * (e.g. 1575 = $15.75). Required. Semantics against the cart's balance due:
-     *   - missing            → error
+     * (e.g. 1575 = $15.75). Required whenever the balance due is greater than
+     * $0; may be omitted only on a cart that already nets to a $0 balance due
+     * (e.g. fully discounted), where it defaults to 0. Semantics against the
+     * cart's balance due:
+     *   - missing            → error, unless the balance due is $0 (→ 0)
      *   - less than balance  → partial payment (the POS enters a fixed
      *                          split-payment leg for this amount)
      *   - equal to balance   → full payment
      *   - more than balance  → error
      */
-    amount: number;
+    amount?: number;
     /** Override the fulfillment state after full payment. kaching resolves the cascade. */
     checkoutFulfillmentTarget?: string;
 }

package/dist/actions/void-order/types.d.ts

@@ -3,9 +3,10 @@ export interface VoidOrderParams {
     /** Order to void; defaults to the active order. */
     orderId?: string;
     /**
-     * Optional cashier-facing reason. On a pure void, recorded on the void audit
-     * row and carried on the `order-voided` event. On the refund branch it rides
-     * the event only — the refund dispatcher does not consume it.
+     * Optional cashier-facing reason. Recorded on both branches — the void audit
+     * trail on a pure void, and (verbatim) on the persisted refund plus its own
+     * audit trail on the refund branch — and always carried on the
+     * `order-voided` event either way.
      */
     reason?: string;
 }

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.1",
+  "version": "0.5.0-preprod.10",
   "description": "Commands Frame library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",