@final-commerce/command-frame 0.5.0-preprod.5 → 0.5.0-preprod.8

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

@@ -17,10 +17,67 @@ 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 only when a refund selection exists on the ACTIVE order (i.e. after
+ * `selectAllRefundItems` / `setRefundItemQuantity`); omitted for a pure
+ * capacity read of some other order.
+ */
+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/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

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