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

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-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/process-partial-refund/mock.js

@@ -1,12 +1,20 @@
 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.
+    // 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,

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. */

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

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