@final-commerce/command-frame 0.3.2-preprod.1 → 0.4.1-preprod.1

package/README.md

@@ -10,13 +10,13 @@ Command Frame provides a structured way to build integrations that run inside Fi
 
 The library provides three main capabilities:
 
-| Capability                | Purpose                                                                                         | Scope                                          |
-| ------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------- |
-| **Commands**              | Call host functions from the iframe (e.g. get products, open cash drawer)                       | Request/response per call                      |
-| **Pub/Sub**               | Subscribe to real-time events from the host (e.g. cart changes, payments)                       | Page-scoped (while iframe is mounted)          |
-| **Hooks**                 | Register business-logic callbacks that persist across all pages                                 | Session-scoped (survives page navigation)      |
-| **Interceptors**          | Gate POS flows (approve / modify / block) at named points                                       | Blocking; host waits for your response         |
-| **Host → iframe refunds** | Render asks the extension to reverse redeem / gift-card payments before completing a POS refund | Parent `postMessage` + `requestId` (see below) |
+| Capability          | Purpose                                                                   | Scope                                     |
+| ------------------- | ------------------------------------------------------------------------- | ----------------------------------------- |
+| **Commands**        | Call host functions from the iframe (e.g. get products, open cash drawer) | Request/response per call                 |
+| **Pub/Sub**         | Subscribe to real-time events from the host (e.g. cart changes, payments) | Page-scoped (while iframe is mounted)     |
+| **Hooks**           | Register business-logic callbacks that persist across all pages           | Session-scoped (survives page navigation) |
+| **Interceptors**    | Gate POS flows (approve / modify / block) at named points                 | Blocking; host waits for your response    |
+| **Refund commands** | Refund payments to gift cards or redeem tenders via `redeemRefund`, or mixed-destination legs on `processPartialRefund`; query engine capacity with `getRefundPlan` | Request/response per call                 |
 
 Domain models (orders, cart, customers, products, and related types) are documented in **[Types reference](./src/types/README.md)**.
 
@@ -71,7 +71,7 @@ For building applications that run inside the Render Point of Sale interface.
 - **Features:** Order management, Product catalog, Customer management, Payments, Hardware integration (Cash drawer, Printer), Custom tables, Secrets storage.
 
 ```typescript
-import { RenderClient } from "@final-commerce/command-frame";
+import { RenderClient } from '@final-commerce/command-frame';
 
 const client = new RenderClient();
 const products = await client.getProducts();
@@ -85,7 +85,7 @@ For building applications that run inside the Final Commerce Management Dashboar
 - **Features:** Context, catalog, entities, custom tables, secrets, and optional host-specific commands (navigation, media, tax, branding, notifications) when the dashboard implements them.
 
 ```typescript
-import { ManageClient } from "@final-commerce/command-frame";
+import { ManageClient } from '@final-commerce/command-frame';
 
 const client = new ManageClient();
 const context = await client.getContext();
@@ -99,14 +99,14 @@ The pub/sub system allows iframe extensions to subscribe to topics and receive r
 - **Topics:** Cart (16), Customers (8), Orders (5), Payments (2), Products (4), Refunds (4), Print (3), Custom Tables (3), Outlet (2), Station (2), Session (2), Users (2).
 
 ```typescript
-import { topics } from "@final-commerce/command-frame";
+import { topics } from '@final-commerce/command-frame';
 
-const subscriptionId = topics.subscribe("cart", event => {
-    console.log("Cart event:", event.type, event.data);
+const subscriptionId = topics.subscribe('cart', (event) => {
+  console.log('Cart event:', event.type, event.data);
 });
 
 // Unsubscribe when done
-topics.unsubscribe("cart", subscriptionId);
+topics.unsubscribe('cart', subscriptionId);
 ```
 
 ## Hooks
@@ -118,21 +118,21 @@ Hooks are **session-scoped** event callbacks that run in the host (Render) conte
 - A stable `hookId` is required for deduplication (safe on iframe reload).
 
 ```typescript
-import { hooks } from "@final-commerce/command-frame";
+import { hooks } from '@final-commerce/command-frame';
 
 hooks.register(
-    "cart",
-    async (event, hostCommands) => {
-        await hostCommands.upsertCustomTableData({
-            tableName: "cart-events-log",
-            data: { eventType: event.type, payload: event.data, timestamp: event.timestamp }
-        });
-    },
-    { hookId: "my-extension:cart-log" }
+  'cart',
+  async (event, hostCommands) => {
+    await hostCommands.upsertCustomTableData({
+      tableName: 'cart-events-log',
+      data: { eventType: event.type, payload: event.data, timestamp: event.timestamp },
+    });
+  },
+  { hookId: 'my-extension:cart-log' },
 );
 
 // Unregister when no longer needed
-hooks.unregister("my-extension:cart-log");
+hooks.unregister('my-extension:cart-log');
 ```
 
 ## Interceptors
@@ -147,43 +147,40 @@ Interceptors let an extension **gate a POS flow** (approve / modify / block) at
 import { interceptors } from '@final-commerce/command-frame';
 
 interceptors.register(
-    'refund_start',
-    async (payload, cmds) => {
-        if (payload.paymentTypes.includes('redeem')) {
-            return cmds.openExtensionOverlay({ point: 'refund_start', payload });
-        }
-        return true; // nothing for us to do
-    },
-    { interceptorId: 'my-extension:refund-guard' }
+  'refund_start',
+  async (payload, cmds) => {
+    if (payload.paymentTypes.includes('redeem')) {
+      return cmds.openExtensionOverlay({ point: 'refund_start', payload });
+    }
+    return true; // nothing for us to do
+  },
+  { interceptorId: 'my-extension:refund-guard' },
 );
 ```
 
-## Host-initiated extension refunds (redeem / gift card)
+## Refunding redeem / extension payments
 
-**Extensions that accept redeem / extension payments must implement a refund listener.** When staff refund an order paid with `paymentType: "redeem"`, Render (host) `postMessage`s into your iframe **before** it records the refund locally. If your app does not handle this message, redeem refunds will time out or fail.
+When staff refund an order that was paid with `paymentType: "redeem"` (via `redeemPayment` or `extensionPayment`), use the **`redeemRefund`** command to refund the amount onto a gift card or redeem tender.
 
-### What you should do
-
-1. **Recommended:** call **`installExtensionRefundListener`** once when your extension boots (e.g. next to your `RenderClient` setup). Pass an `async` handler that calls your provider (gift card API, wallet, etc.) and returns an **`ExtensionRefundResponse`** (`success`, optional `error`, optional `extensionTransactionId` for receipts / support).
-2. The helper validates `event.source === window.top`, parses params, and replies with the same **`PostMessageResponse`** envelope as the rest of Command Frame (`requestId`, `success`, `data` / `error`).
-3. **Alternative:** implement a `window` `message` listener yourself using the same contract (action name: **`extensionRefundRequest`**, or import **`EXTENSION_REFUND_REQUEST_ACTION`** from this package).
-
-Exported APIs: `installExtensionRefundListener`, `EXTENSION_REFUND_REQUEST_ACTION`, types **`ExtensionRefundParams`** / **`ExtensionRefundResponse`**.
+**Key point:** Plain refunds on redeem sources still fail by design (`REDEEM_REFUND_UNSUPPORTED`). Use `redeemRefund` to refund onto a gift card when your extension credits the card first.
 
 ```typescript
-import { installExtensionRefundListener, type ExtensionRefundParams, type ExtensionRefundResponse } from "@final-commerce/command-frame";
-
-const unsubscribe = installExtensionRefundListener(async (params: ExtensionRefundParams): Promise<ExtensionRefundResponse> => {
-    // params.paymentType === "redeem", params.amount in major currency units, params.saleId, params.processor, etc.
-    const ok = await myGiftCardProvider.refund(params);
-    return ok ? { success: true, extensionTransactionId: ok.providerRefundId } : { success: false, error: "Refund declined" };
+import { command } from '@final-commerce/command-frame';
+
+// Refund a redeem order back onto a gift card
+const result = await command.redeemRefund({
+  orderId: 'order_123',
+  amount: 2500, // $25.00
+  referenceId: 'GIFTCARD-456', // destination card
+  processor: 'giftCard',
+  label: 'Gift Card Refund',
+  reason: 'Customer requested return',
 });
-
-// on teardown (optional)
-// unsubscribe();
 ```
 
-**Full protocol, edge cases, and manual handling:** **[Extension refund documentation](./src/actions/extension-refund/README.md)**.
+**Full documentation:** **[redeemRefund](./src/actions/redeem-refund/README.md)**.
+
+Before prompting the cashier for an amount, query **[getRefundPlan](./src/actions/get-refund-plan/README.md)** (read-only) for the order's own per-source caps (`maxRefundable`, `cardNumber` for same-card prefill) and order-level `remainingRefundable` — don't recompute this client-side, and always handle a `REFUND_AMOUNT_EXCEEDS_CAPACITY` rejection from the mutating call since the plan is only an advisory snapshot.
 
 ## Development & Testing
 

package/dist/actions/apply-transition/mock.d.ts

@@ -1,6 +1,6 @@
 import type { ApplyTransitionParams, ApplyTransitionResponse } from "./types";
 /**
- * Mock implementation: applies all transitions except a few known-invalid ones
+ * Mock implementation: applies all transitions except a known-invalid one
  * so the demo app can show both successful and blocked responses.
  */
 export declare const applyTransitionMock: (params: ApplyTransitionParams) => Promise<ApplyTransitionResponse>;

package/dist/actions/apply-transition/mock.js

@@ -1,33 +1,23 @@
 /**
- * Mock implementation: applies all transitions except a few known-invalid ones
+ * Mock implementation: applies all transitions except a known-invalid one
  * so the demo app can show both successful and blocked responses.
  */
 export const applyTransitionMock = (params) => {
-    const { to } = params;
-    if (to.payment === "refunded" && to.fulfillment === "draft") {
+    const { targetFulfillmentState } = params;
+    if (targetFulfillmentState === "cancelled") {
         return Promise.resolve({
             result: {
                 allowed: false,
-                blockedBy: "financial_invariant",
-                guard: "no-refund-in-draft",
-                reason: "Cannot refund an order that is still in draft"
-            }
-        });
-    }
-    if (to.payment === "paid" && to.fulfillment === "cancelled") {
-        return Promise.resolve({
-            result: {
-                allowed: false,
-                blockedBy: "cross_axis_rule",
-                guard: "no-pay-cancelled",
-                reason: "Cannot mark a cancelled order as paid"
+                blockedBy: "condition",
+                guard: "no-cancel-open-order",
+                reason: "Cannot cancel an order with open items"
             }
         });
     }
     return Promise.resolve({
         result: { allowed: true },
         from: { payment: "unpaid", fulfillment: "draft" },
-        to,
-        displayState: `${to.payment} / ${to.fulfillment}`
+        to: { payment: "unpaid", fulfillment: targetFulfillmentState },
+        displayState: `unpaid / ${targetFulfillmentState}`
     });
 };

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

@@ -1,9 +1,11 @@
 import type { CFStatePair, CFTransitionResult } from "../../common-types/order-state";
 export interface ApplyTransitionParams {
-    /** Order to transition. */
-    orderId: string;
-    /** Target state pair. */
-    to: CFStatePair;
+    /** Order to transition. Omit to target the active order — materializing one from the live cart if none exists. */
+    orderId?: string;
+    /** Target fulfillment state. The payment axis is never client-settable. */
+    targetFulfillmentState: string;
+    /** Clear the terminal after transitioning the ACTIVE order (park parity). Default true. */
+    clearTerminal?: boolean;
 }
 export interface ApplyTransitionResponse {
     result: CFTransitionResult;

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

@@ -15,8 +15,8 @@ export interface ExtensionPaymentParams {
     referenceId?: string;
     extensionId?: string;
     metadata?: Record<string, unknown>;
-    /** Override the fulfillment state after full payment. Render resolves the cascade. */
-    checkoutFulfillmentTarget?: string;
+    /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
+    targetFulfillmentState?: string;
     /** EMV data when the underlying payment carries one (typed as `IntegrationEmvData` by the integration wrapper). */
     emvData?: unknown;
     /** Processor fee in integer MINOR currency units; recorded on the order's paymentMethod.processorFee. */

package/dist/actions/get-available-transitions/mock.d.ts

@@ -1,6 +1,8 @@
-import type { GetAvailableTransitionsParams, GetAvailableTransitionsResponse } from "./types";
+import type { GetAvailableTransitions } from "./types";
 /**
  * Mock implementation: returns a fixed set of plausible transitions
- * so the demo app has data to render.
+ * so the demo app has data to render. Mirrors an UNPAID order under the
+ * default (empty cross-axis rules) config: fulfillment can advance without
+ * payment (FI-6383), plus the classic park/void moves.
  */
-export declare const getAvailableTransitionsMock: (_params: GetAvailableTransitionsParams) => Promise<GetAvailableTransitionsResponse>;
+export declare const getAvailableTransitionsMock: GetAvailableTransitions;

package/dist/actions/get-available-transitions/mock.js

@@ -1,26 +1,38 @@
 /**
  * Mock implementation: returns a fixed set of plausible transitions
- * so the demo app has data to render.
+ * so the demo app has data to render. Mirrors an UNPAID order under the
+ * default (empty cross-axis rules) config: fulfillment can advance without
+ * payment (FI-6383), plus the classic park/void moves.
  */
-export const getAvailableTransitionsMock = async (_params) => ({
+export const getAvailableTransitionsMock = () => Promise.resolve({
     transitions: [
         {
-            to: { payment: "refunded", fulfillment: "returned" },
-            displayLabel: "Full Refund",
-            conditions: [{ met: true, description: "Order is paid" }],
+            to: { payment: "unpaid", fulfillment: "in_progress" },
+            displayLabel: "Start Preparing",
+            conditions: [{ met: true, description: "Order has items" }]
         },
         {
-            to: { payment: "partially_refunded", fulfillment: "partially_returned" },
-            displayLabel: "Partial Refund",
-            conditions: [{ met: true, description: "Order is paid" }],
+            to: { payment: "unpaid", fulfillment: "fulfilled" },
+            displayLabel: "Mark Fulfilled",
+            conditions: [{ met: true, description: "Order has items" }]
+        },
+        {
+            to: { payment: "unpaid", fulfillment: "on_hold" },
+            displayLabel: "Park Order",
+            conditions: [{ met: true, description: "Order is open" }]
+        },
+        {
+            to: { payment: "paid", fulfillment: "fulfilled" },
+            displayLabel: "Complete Payment",
+            conditions: [{ met: true, description: "Balance due > 0" }]
         },
         {
             to: { payment: "voided", fulfillment: "cancelled" },
             displayLabel: "Void Order",
             conditions: [
                 { met: true, description: "Order exists" },
-                { met: false, description: "No payments captured (mock: skipped)" },
-            ],
-        },
-    ],
+                { met: false, description: "No payments captured (mock: skipped)" }
+            ]
+        }
+    ]
 });

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

@@ -0,0 +1,6 @@
+/**
+ * Get refund plan action
+ * Calls the getRefundPlan action on the parent window
+ */
+import type { GetRefundPlan } from './types';
+export declare const getRefundPlan: GetRefundPlan;

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

@@ -0,0 +1,8 @@
+/**
+ * Get refund plan action
+ * Calls the getRefundPlan action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const getRefundPlan = async (params) => {
+    return await commandFrameClient.call('getRefundPlan', params);
+};

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

@@ -0,0 +1,14 @@
+import { GetRefundPlan } from './types';
+/**
+ * Demo derivation of the runtime `getRefundPlan`. Builds the per-source rows
+ * from the mock order's `paymentMethods`, mirroring the runtime's capacity
+ * definition (principal + captured tip).
+ *
+ * HONEST INERTNESS: the demo DB records no prior-refund ledger and no `emv`
+ * blocks on its mock captures, so this mock reports `refundedAmount: 0` /
+ * `totalRefunded: 0` and `cardNumber: undefined` for every source, and treats
+ * `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.
+ */
+export declare const mockGetRefundPlan: GetRefundPlan;

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

@@ -0,0 +1,59 @@
+import { MOCK_ORDERS } from '../../demo/database';
+/**
+ * Demo derivation of the runtime `getRefundPlan`. Builds the per-source rows
+ * from the mock order's `paymentMethods`, mirroring the runtime's capacity
+ * definition (principal + captured tip).
+ *
+ * HONEST INERTNESS: the demo DB records no prior-refund ledger and no `emv`
+ * blocks on its mock captures, so this mock reports `refundedAmount: 0` /
+ * `totalRefunded: 0` and `cardNumber: undefined` for every source, and treats
+ * `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.
+ */
+export const mockGetRefundPlan = async (params) => {
+    console.log('[Mock] getRefundPlan called', params);
+    const order = params?.orderId ? MOCK_ORDERS.find((o) => o._id === params.orderId) : MOCK_ORDERS[0];
+    if (!order) {
+        throw new Error(`Order with ID ${params?.orderId} not found`);
+    }
+    const capturedOf = (pm) => Math.round(pm.amount ?? 0) + Math.round(pm.tip?.amount ?? 0);
+    const sources = (order.paymentMethods ?? []).map((pm) => {
+        const captured = capturedOf(pm);
+        let cardNumber;
+        // Demo captures carry no emv, so this is always undefined here; kept to
+        // document the runtime's redeem-source card-number extraction.
+        if (pm.paymentType === 'redeem' && pm.emv) {
+            try {
+                cardNumber = JSON.parse(pm.emv)['Card Number'];
+            }
+            catch {
+                cardNumber = undefined;
+            }
+        }
+        return {
+            transactionId: pm.transactionId,
+            paymentType: pm.paymentType,
+            processor: pm.processor ?? undefined,
+            capturedAmount: captured,
+            // Demo DB has no refund ledger — nothing has been refunded yet here.
+            refundedAmount: 0,
+            maxRefundable: captured,
+            refundableToSource: pm.paymentType !== 'redeem',
+            cardNumber,
+        };
+    });
+    const totalCaptured = sources.reduce((sum, s) => sum + s.capturedAmount, 0);
+    const nonRefundableLiability = order.summary?.nonRevenueTotal ?? 0;
+    return {
+        success: true,
+        orderId: order._id,
+        sources,
+        // Demo: no prior refunds, so remaining = captured minus the non-revenue load.
+        remainingRefundable: Math.max(0, totalCaptured - nonRefundableLiability),
+        nonRefundableLiability,
+        totalCaptured,
+        totalRefunded: 0,
+        timestamp: new Date().toISOString(),
+    };
+};

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

@@ -0,0 +1,32 @@
+export interface GetRefundPlanParams {
+    /** Order to inspect; defaults to the active order. */
+    orderId?: string;
+}
+export interface RefundPlanSource {
+    transactionId: string;
+    paymentType: string;
+    processor?: string;
+    /** Captured on this payment (minor units). */
+    capturedAmount: number;
+    /** Already refunded against this source (minor units). */
+    refundedAmount: number;
+    /** Remaining refundable on this source (minor units) — the engine's own per-source cap. */
+    maxRefundable: number;
+    /** False for sources the engine cannot refund to directly (redeem without a gift-card destination). */
+    refundableToSource: boolean;
+    /** For redeem sources: the card number from the payment entry's emv, when present. */
+    cardNumber?: string;
+}
+export interface GetRefundPlanResponse {
+    success: boolean;
+    orderId: string;
+    sources: RefundPlanSource[];
+    /** Order-level remaining refundable (minor units) — non-revenue liability already excluded. */
+    remainingRefundable: number;
+    /** Non-refundable liability (gift-card loads etc., minor units). */
+    nonRefundableLiability: number;
+    totalCaptured: number;
+    totalRefunded: number;
+    timestamp: string;
+}
+export type GetRefundPlan = (params?: GetRefundPlanParams) => Promise<GetRefundPlanResponse>;

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

@@ -0,0 +1,7 @@
+// Get Refund Plan Types
+//
+// READ-ONLY capacity query. Exposes the refund engine's OWN per-source and
+// 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).
+export {};

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

@@ -51,6 +51,8 @@ export interface IntegrationPaymentParams {
     metadata?: Record<string, unknown>;
     /** Provider fee in integer MINOR currency units — stored on paymentMethod.processorFee. */
     processorFee?: number;
+    /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
+    targetFulfillmentState?: string;
 }
 export type IntegrationPaymentResponse = ExtensionPaymentResponse;
 export type IntegrationPayment = (params: IntegrationPaymentParams) => Promise<IntegrationPaymentResponse>;

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

@@ -7,8 +7,8 @@ export interface PartialPaymentParams {
     isPercent?: boolean;
     /** If true, opens the split payment UI. */
     openUI?: boolean;
-    /** Override the fulfillment state after full payment. Render resolves the cascade. */
-    checkoutFulfillmentTarget?: string;
+    /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
+    targetFulfillmentState?: string;
 }
 export interface PartialPaymentResponse {
     success: boolean;

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

@@ -1,5 +1,13 @@
 export const mockProcessPartialRefund = async (params) => {
-    console.log("[Mock] processPartialRefund called", 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", {
+        ...params,
+        openUI: params?.openUI ?? true,
+        legs: params?.legs ?? null,
+    });
     return {
         success: true,
         refundId: 'mock_refund_' + Date.now(),

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

@@ -1,15 +1,113 @@
 import type { CFTransitionResult } from "../../common-types/order-state";
 export interface ProcessPartialRefundParams {
-    /** Optional refund reason. */
+    /**
+     * 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.
+     */
     reason?: string;
     /** Optional: specify which order to refund (sets it as active). */
     orderId?: string;
+    /**
+     * Controls the refund UI for a MULTI-TENDER order (one paid across more
+     * than one payment method). Defaults to `true`.
+     *
+     * - `true` (default, back-compat): the POS raises its split-payment refund
+     *   modal so the cashier allocates the refund across the original payment
+     *   sources; `processPartialRefund` returns without committing and the
+     *   modal drives the commit.
+     * - `false`: no modal is raised — the refund is committed headlessly
+     *   against the planner's default proportional allocation across those
+     *   sources (all cash-rounding invariants preserved). Use this when your
+     *   flow renders its own refund UI and needs a fully headless multi-tender
+     *   partial refund.
+     *
+     * Has no effect on single-tender orders (already headless — there is
+     * nothing to allocate).
+     */
+    openUI?: boolean;
+    /**
+     * Explicit per-tender allocation for the refund — the headless replacement
+     * for choosing, in the split-payment refund modal, WHICH original payment
+     * each refunded dollar returns to. Each entry names an original payment by
+     * its `transactionId` and the amount, **in minor units** (cents), to return
+     * to that source.
+     *
+     * Requires `openUI: false` — with the modal path (`openUI` omitted/`true`)
+     * the modal owns allocation and `legs` are ignored. Validation:
+     * - Σ of all `amount`s **must equal the allocatable refund budget** —
+     *   `min(the refund total computed from the selected items, Σ of each
+     *   source's remaining refundable capacity)`; on a full selection this is
+     *   the captured total and the cash-rounding gap is auto-stamped (a
+     *   mismatch throws; nothing is committed);
+     * - the amounts **aggregated per source** must be ≤ that source's remaining
+     *   refundable capacity (over-cap throws, naming the source);
+     * - a **zero** `amount` entry is IGNORED — dropped like an omitted row,
+     *   matching the modal (which let a cashier leave a tender at 0 and filtered
+     *   it at commit) — while a **negative** `amount` is rejected;
+     * - an unknown `transactionId` throws, naming it.
+     *
+     * MIXED RETURNS — set `giftCard` on a leg to land that leg's amount on a
+     * gift-card / store-credit tender instead of returning it to the source. A
+     * single `legs` array may freely mix source-return legs and `giftCard` legs
+     * (some money back to the original tenders, the rest onto a card). An
+     * all-`giftCard` staging is the `redeemRefund` equivalent through this path.
+     * **Credit-first:** the flow must credit the card for the sum of all
+     * `giftCard` legs BEFORE calling; on any throw nothing was recorded — reverse
+     * the credit.
+     *
+     * Omit `legs` to keep the default proportional allocation across sources.
+     * See "Choosing which payments to refund to" and "Mixed returns" in the README.
+     */
+    legs?: {
+        /** `transactionId` of the original payment this leg draws from. */
+        transactionId: string;
+        /** Amount for this leg, in minor units (cents). `0` is ignored (dropped
+         *  like an omitted row); a negative value is rejected. */
+        amount: number;
+        /**
+         * When set, this leg's amount lands on the gift-card / store-credit
+         * ("redeem") tender instead of returning to the source. The leg still
+         * draws from `transactionId` for capacity/audit — only the landing
+         * tender changes.
+         *
+         * CREDIT-FIRST: the flow must have already credited the card for the sum
+         * of all `giftCard` legs before calling; on any throw nothing was
+         * recorded and the caller must reverse that credit. `referenceId` is
+         * required when `giftCard` is present.
+         */
+        giftCard?: {
+            /** Card/account id the flow already credited (stored raw). */
+            referenceId: string;
+            /** 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. */
         itemKey: string;
         quantity: number;
         type?: 'product' | 'customSale' | 'fee' | 'tip';
+        /**
+         * Per-item stock disposition for a refunded **product** line — the
+         * headless equivalent of the old refund popup's per-row restock/damaged
+         * dropdown. Recorded on the persisted refund line so hub-side inventory
+         * ingest knows whether the returned units go back on the shelf.
+         *
+         * - `'RESTOCK'` (default when omitted): units return to sellable stock
+         *   — the popup's default first option.
+         * - `'REFUND_DAMAGE'`: units are written off as damaged, not restocked.
+         *
+         * Ignored for non-`product` items (custom sales / fees / tips carry no
+         * stock action, exactly as the popup only offered it on line items).
+         */
+        stockAction?: 'RESTOCK' | 'REFUND_DAMAGE';
     }[];
 }
 export interface ProcessPartialRefundResponse {

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

@@ -12,6 +12,8 @@ export interface RedeemPaymentParams {
     processor?: string;
     referenceId?: string;
     metadata?: Record<string, unknown>;
+    /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
+    targetFulfillmentState?: string;
 }
 export type RedeemPaymentResponse = ExtensionPaymentResponse;
 export type RedeemPayment = (params: RedeemPaymentParams) => Promise<RedeemPaymentResponse>;

package/dist/actions/redeem-refund/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Redeem refund action
+ * Calls the redeemRefund action on the parent window
+ */
+import type { RedeemRefund } from './types';
+export declare const redeemRefund: RedeemRefund;

package/dist/actions/redeem-refund/action.js

@@ -0,0 +1,8 @@
+/**
+ * Redeem refund action
+ * Calls the redeemRefund action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const redeemRefund = async (params) => {
+    return await commandFrameClient.call('redeemRefund', params);
+};

package/dist/actions/redeem-refund/mock.d.ts

@@ -0,0 +1,2 @@
+import { RedeemRefund } from './types';
+export declare const mockRedeemRefund: RedeemRefund;