@final-commerce/command-frame 0.7.0 → 0.7.1

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

@@ -15,5 +15,9 @@ import { GetRefundPlan } from './types';
  * 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.
+ *
+ * `rows` / `allocation.breakdown` follow the engine's reading of the order
+ * (`line.total` includes the line's tax) but prorate by plain quantity share;
+ * the engine's remainder carry across earlier partial refunds is not modelled.
  */
 export declare const mockGetRefundPlan: GetRefundPlan;

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

@@ -1,4 +1,5 @@
 import { MOCK_ORDERS } from '../../demo/database';
+import { mockRefundBreakdown, mockRefundRows } from './mockRows';
 /**
  * Demo derivation of the runtime `getRefundPlan`. Builds the per-source rows
  * from the mock order's `paymentMethods`, mirroring the runtime's capacity
@@ -15,6 +16,10 @@ import { MOCK_ORDERS } from '../../demo/database';
  * 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.
+ *
+ * `rows` / `allocation.breakdown` follow the engine's reading of the order
+ * (`line.total` includes the line's tax) but prorate by plain quantity share;
+ * the engine's remainder carry across earlier partial refunds is not modelled.
  */
 export const mockGetRefundPlan = async (params) => {
     console.log('[Mock] getRefundPlan called', params);
@@ -62,16 +67,19 @@ export const mockGetRefundPlan = async (params) => {
         requiresGiftCardDestination: s.paymentType === 'redeem',
     }));
     const budget = legs.reduce((sum, l) => sum + l.amount, 0);
+    const rows = mockRefundRows(order);
     return {
         success: true,
         orderId: order._id,
         sources,
+        rows,
         allocation: {
             budget,
             // No cash rounding in the demo, so the goods value and the budget agree.
             itemTotal: budget,
             rounding: 0,
             legs,
+            breakdown: mockRefundBreakdown(rows, params?.items),
         },
         // Demo: no prior refunds, so remaining = captured minus the non-revenue load.
         remainingRefundable: Math.max(0, totalCaptured - nonRefundableLiability),

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

@@ -0,0 +1,6 @@
+import type { CFActiveOrder } from '../../CommonTypes';
+import type { GetRefundPlanParams, RefundPlanBreakdown, RefundPlanRow } from './types';
+/** Every row of a demo order. The demo has no refund ledger, so everything is refundable. */
+export declare function mockRefundRows(order: CFActiveOrder): RefundPlanRow[];
+/** The selection's breakdown; no `items` means everything, like the demo's full-refund legs. */
+export declare function mockRefundBreakdown(rows: RefundPlanRow[], items?: GetRefundPlanParams['items']): RefundPlanBreakdown;

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

@@ -0,0 +1,114 @@
+// Demo derivation of `getRefundPlan`'s `rows` and `allocation.breakdown`, for
+// local/standalone mode only. See the note on `mockGetRefundPlan`.
+const minor = (v) => Math.round(Number(v ?? 0)) || 0;
+/** A line's whole-quantity money, reading `total` as tax-inclusive (the engine's reading). */
+function lineAmounts(line) {
+    const tax = minor(line.totalTax);
+    const itemDiscount = (line.discount?.itemDiscounts ?? []).reduce((s, d) => s + minor(d.amount), 0);
+    const cartDiscount = minor(line.discount?.cartDiscount?.amount);
+    const net = Math.max(0, minor(line.total) - tax);
+    const taxes = (line.taxes ?? []).map((t) => ({
+        name: String(t.name ?? 'Tax'),
+        percentage: t.percentage,
+        amount: minor(t.amount),
+    }));
+    return { subtotal: net + itemDiscount + cartDiscount, itemDiscount, cartDiscount, tax, taxes, total: net + tax };
+}
+function scale(a, share) {
+    if (share >= 1)
+        return a;
+    const r = (n) => Math.round(n * share);
+    const out = {
+        subtotal: r(a.subtotal),
+        itemDiscount: r(a.itemDiscount),
+        cartDiscount: r(a.cartDiscount),
+        tax: r(a.tax),
+        taxes: a.taxes.map((t) => ({ ...t, amount: r(t.amount) })),
+    };
+    return { ...out, total: out.subtotal - out.itemDiscount - out.cartDiscount + out.tax };
+}
+/** Every row of a demo order. The demo has no refund ledger, so everything is refundable. */
+export function mockRefundRows(order) {
+    const rows = [];
+    for (const li of order.lineItems ?? []) {
+        const itemKey = String(li.internalId || li.variantId || '');
+        if (!itemKey || !(li.quantity > 0))
+            continue;
+        rows.push({
+            type: 'product',
+            itemKey,
+            label: String(li.name ?? 'Item'),
+            ...(li.sku ? { sku: li.sku } : {}),
+            ...(li.attributes ? { attributes: li.attributes } : {}),
+            quantity: li.quantity,
+            refundableQuantity: li.quantity,
+            amounts: lineAmounts(li),
+        });
+    }
+    for (const cs of order.customSales ?? []) {
+        if (!cs.customSaleId || !(cs.quantity > 0))
+            continue;
+        rows.push({
+            type: 'customSale',
+            itemKey: cs.customSaleId,
+            label: String(cs.name ?? 'Custom sale'),
+            quantity: cs.quantity,
+            refundableQuantity: cs.quantity,
+            amounts: lineAmounts(cs),
+        });
+    }
+    for (const fee of order.cartFees ?? []) {
+        const amount = minor(fee.amount);
+        const tax = minor(fee.tax);
+        rows.push({
+            type: 'fee',
+            itemKey: String(fee.id),
+            label: String(fee.label || 'Cart fee'),
+            quantity: 1,
+            refundableQuantity: 1,
+            amounts: { subtotal: amount, itemDiscount: 0, cartDiscount: 0, tax, taxes: [], total: amount + tax },
+        });
+    }
+    for (const pm of order.paymentMethods ?? []) {
+        const tip = minor(pm.tip?.amount);
+        if (tip <= 0)
+            continue;
+        rows.push({
+            type: 'tip',
+            itemKey: pm.transactionId,
+            label: 'Tip',
+            paymentType: pm.paymentType,
+            quantity: 1,
+            refundableQuantity: 1,
+            amounts: { subtotal: tip, itemDiscount: 0, cartDiscount: 0, tax: 0, taxes: [], total: tip },
+        });
+    }
+    return rows;
+}
+/** The selection's breakdown; no `items` means everything, like the demo's full-refund legs. */
+export function mockRefundBreakdown(rows, items) {
+    const picked = new Map((items ?? []).map((i) => [i.itemKey, i.quantity]));
+    const selected = rows
+        .map((row) => {
+        const quantity = items?.length
+            ? Math.min(picked.get(row.itemKey) ?? 0, row.refundableQuantity)
+            : row.refundableQuantity;
+        return { type: row.type, itemKey: row.itemKey, quantity, amounts: scale(row.amounts, quantity / row.quantity) };
+    })
+        .filter((r) => r.quantity > 0);
+    const totals = { items: 0, discounts: 0, fees: 0, tax: 0, tip: 0, total: 0 };
+    for (const r of selected) {
+        const a = r.amounts;
+        if (r.type === 'fee')
+            totals.fees += a.subtotal;
+        else if (r.type === 'tip')
+            totals.tip += a.subtotal;
+        else {
+            totals.items += a.subtotal;
+            totals.discounts += a.itemDiscount + a.cartDiscount;
+        }
+        totals.tax += a.tax;
+        totals.total += a.total;
+    }
+    return { rows: selected, totals };
+}

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

@@ -76,6 +76,81 @@ export interface RefundPlanLeg {
         rounding: number;
     };
 }
+export type RefundPlanRowType = 'product' | 'customSale' | 'fee' | 'tip';
+/** One tax rate's share of a row's refund (minor units). */
+export interface RefundPlanTaxLine {
+    name: string;
+    /** Decimal rate as stored on the order (e.g. `0.15`), when the order recorded one. */
+    percentage?: number;
+    amount: number;
+}
+/**
+ * The money a row refunds, split the way a receipt shows it. Every field is
+ * minor units and already rounded; `subtotal − itemDiscount − cartDiscount +
+ * tax === total` always holds. DISPLAY IT — never re-add or prorate it.
+ */
+export interface RefundPlanAmounts {
+    /** Before discounts, tax excluded. For a tip row, the tip itself. */
+    subtotal: number;
+    /** Per-item discounts on the refunded quantity (positive). */
+    itemDiscount: number;
+    /** Cart discount share on the refunded quantity (positive). */
+    cartDiscount: number;
+    /** Tax on the refunded quantity. Zero for a tip. */
+    tax: number;
+    /** `tax` per rate — the price breakdown's tax lines. */
+    taxes: RefundPlanTaxLine[];
+    /** What the row refunds. */
+    total: number;
+}
+/**
+ * One refundable row of the order — a line item, custom sale, cart fee or tip —
+ * served ready to render. Rows with nothing left to refund are not listed.
+ */
+export interface RefundPlanRow {
+    type: RefundPlanRowType;
+    /** The key `items[].itemKey` takes, for this call and for `processPartialRefund`. */
+    itemKey: string;
+    /** Line or fee name; `Tip` for a tip. */
+    label: string;
+    /** Product lines only, when the order recorded them. */
+    sku?: string;
+    attributes?: string;
+    /** Tip rows only: the tender that took the tip (`card`, `cash`, …). */
+    paymentType?: string;
+    /** Quantity originally sold. Fees and tips are `1` — all or nothing. */
+    quantity: number;
+    /** Quantity still refundable — the stepper's max. */
+    refundableQuantity: number;
+    /** The money for refunding ALL of `refundableQuantity`. */
+    amounts: RefundPlanAmounts;
+}
+/** One selected row and what refunding the selected quantity of it moves. */
+export interface RefundPlanSelectedRow {
+    type: RefundPlanRowType;
+    itemKey: string;
+    quantity: number;
+    amounts: RefundPlanAmounts;
+}
+/**
+ * The selection's goods value broken down for display. Minor units;
+ * `items − discounts + fees + tax + tip === total === allocation.itemTotal`.
+ */
+export interface RefundPlanTotals {
+    /** Σ selected line subtotals (before discounts, tax excluded). */
+    items: number;
+    /** Σ item + cart discounts on the selected lines (positive). */
+    discounts: number;
+    /** Σ selected cart fees, tax excluded. */
+    fees: number;
+    tax: number;
+    tip: number;
+    total: number;
+}
+export interface RefundPlanBreakdown {
+    rows: RefundPlanSelectedRow[];
+    totals: RefundPlanTotals;
+}
 /**
  * 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
@@ -103,11 +178,25 @@ export interface RefundPlanAllocation {
     rounding: number;
     /** One leg per source that receives money. Submit as `legs`, unchanged. */
     legs: RefundPlanLeg[];
+    /**
+     * What the selection refunds, per row and in total — the numbers a refund
+     * dialog's rows and footer render. Optional so an older runtime still
+     * type-checks; kaching 1.12.1+ always sends it.
+     */
+    breakdown?: RefundPlanBreakdown;
 }
 export interface GetRefundPlanResponse {
     success: boolean;
     orderId: string;
     sources: RefundPlanSource[];
+    /**
+     * Every row still refundable on the order, with the money for refunding all
+     * of it — what a refund dialog lists before anything is selected. Replaces
+     * reading line totals off the order and deciding whether they include tax.
+     * Optional so an older runtime still type-checks; kaching 1.12.1+ always
+     * sends it.
+     */
+    rows?: RefundPlanRow[];
     /**
      * Ready-to-submit allocation of the current selection. Present only when a
      * refund selection exists on the active order. See {@link RefundPlanAllocation}.

package/dist/index.d.ts

@@ -146,7 +146,7 @@ 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, RefundPlanAllocation, RefundPlanLeg, } from './actions/get-refund-plan/types';
+export type { GetRefundPlan, GetRefundPlanParams, GetRefundPlanResponse, RefundPlanSource, RefundPlanAllocation, RefundPlanLeg, RefundPlanRowType, RefundPlanTaxLine, RefundPlanAmounts, RefundPlanRow, RefundPlanSelectedRow, RefundPlanTotals, RefundPlanBreakdown, } 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@final-commerce/command-frame",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Commands Frame library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -73,5 +73,8 @@
     "typescript-eslint": "^8.0.0",
     "vitest": "^4.0.0"
   },
+  "overrides": {
+    "js-yaml": "^4.3.2"
+  },
   "prettier": "@final-commerce/common/prettier"
 }