@sixtyninecommerce/admin 0.11.0 → 0.12.0

package/dist/orders/money-view.d.ts

@@ -0,0 +1,149 @@
+/**
+ * `admin.orders.moneyView(orderId, { basis })`: an order's money as rows that add up exactly to
+ * its own totals, in one basis (pricing-display-consistency, USER O12). Every surface that shows
+ * an order's money prints these rows, so an order page, an email and an invoice cannot disagree
+ * by a cent. The engine builds them (`Order.moneyView`); this module only reads them.
+ */
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Which prices a view shows. `GROSS` = incl. VAT, `NET` = excl. VAT. `STORE` follows how the
+ * store sets its prices; `CUSTOMER` how the shop shows prices to the order's customer. The view
+ * answers the one it used, `GROSS` or `NET`.
+ */
+export declare const ORDER_MONEY_BASES: readonly ["STORE", "CUSTOMER", "GROSS", "NET"];
+export type OrderMoneyBasis = (typeof ORDER_MONEY_BASES)[number];
+/** One order line. Money is an integer in minor units of the view's `currencyCode`. */
+export interface OrderMoneyLine {
+    orderLineId: string;
+    quantity: number;
+    taxRate: number;
+    /**
+     * The unit price, only when the line was priced in this basis (`unitAmount × quantity =
+     * amount`); null in the other basis, where only the line total multiplies out.
+     */
+    unitAmount: number | null;
+    /** The line total before promotions. */
+    amount: number;
+}
+/** A promotion, a surcharge or a shipping line. A discount is negative. */
+export interface OrderMoneyRow {
+    /** The promotion's adjustment source, the surcharge id or the shipping line id. */
+    key: string;
+    description: string;
+    amount: number;
+    /** The row's VAT rate; null for a promotion, which can span several. */
+    taxRate: number | null;
+}
+/** The VAT at one rate: goods, shipping and surcharges together, a staff rounding's VAT in. */
+export interface OrderMoneyTaxRow {
+    taxRate: number;
+    /** Excl. VAT. */
+    base: number;
+    amount: number;
+}
+/**
+ * Why a view gives no still-to-pay figure: `KEPT_IN_ERP`, the order was placed on a B2B account
+ * kept in an external accounting system, so print a note ("paid via your account in the
+ * accounting system") instead of an amount. A new value may be added.
+ */
+export type OrderMoneyStillToPayNote = 'KEPT_IN_ERP';
+/**
+ * What has been paid and what is still to pay, gross; a zero row is not printed. An engine that
+ * answers `stillToPayNote` (null included) reads the B2B account ledger: money paid or credited on
+ * an account invoice is in `paid` and `credited`. Without it (an older engine) it is not, so an
+ * order a live account invoice bills reads its whole remainder as `stillToPay`: do not print that
+ * figure for it.
+ */
+export interface OrderMoneyBalance {
+    /** Money received or held by a payment provider, less refunds; never a payment still to arrive. */
+    paid: number;
+    giftCard: number;
+    storeCredit: number;
+    /** What credit notes took off the bill. */
+    credited: number;
+    /** What the order bills less the four above, never below zero. A bank-transfer or net-terms promise still counts as to pay. Zero when `stillToPayNote` is set. */
+    stillToPay: number;
+    /** Set when no still-to-pay figure can be given (print its note); null otherwise; absent on an older engine. */
+    stillToPayNote?: OrderMoneyStillToPayNote | null;
+}
+/**
+ * The rows and their identities: `Σ lines + Σ goodsAdjustments + Σ surcharges = subtotal`;
+ * `Σ shipping + Σ shippingAdjustments = shippingTotal`; on `GROSS` `subtotal + shippingTotal +
+ * (rounding ?? 0) = total`; on `NET` `subtotal + shippingTotal + taxTotal + (rounding ?? 0) =
+ * total`; `Σ taxes = taxTotal`; `totalExcludingTax + taxTotal = total`.
+ */
+export interface OrderMoneyView {
+    basis: 'GROSS' | 'NET';
+    currencyCode: string;
+    lines: OrderMoneyLine[];
+    /** One row per promotion on the goods (price-list order rules and coupons included). */
+    goodsAdjustments: OrderMoneyRow[];
+    /** Fees (positive) and staff discounts (negative). */
+    surcharges: OrderMoneyRow[];
+    subtotal: number;
+    /** Each shipping line before its promotions. */
+    shipping: OrderMoneyRow[];
+    /** One row per promotion on shipping. */
+    shippingAdjustments: OrderMoneyRow[];
+    shippingTotal: number;
+    /** Everything excl. VAT, a staff rounding's net part in: the invoice's "Total excl. VAT". */
+    totalExcludingTax: number;
+    /** One row per VAT rate. */
+    taxes: OrderMoneyTaxRow[];
+    /** True on `GROSS`: the VAT rows are inside the total, not added to it. */
+    taxIncluded: boolean;
+    taxTotal: number;
+    /** A staff rounding, printed just above the total (gross on `GROSS`, excl. VAT on `NET`). */
+    rounding: number | null;
+    /** What the order bills, incl. VAT, after a staff rounding. */
+    total: number;
+    /** The total before a staff rounding. */
+    totalBeforeRounding: number;
+    balance: OrderMoneyBalance;
+    /** False only when the order's stored totals disagree with its own rows. */
+    reconciles: boolean;
+}
+/** Every field of an `OrderMoneyView`, at every depth: the selection each document reads it with. */
+export declare const ORDER_MONEY_VIEW_FIELDS = "\n        basis\n        currencyCode\n        lines { orderLineId quantity taxRate unitAmount amount }\n        goodsAdjustments { key description amount taxRate }\n        surcharges { key description amount taxRate }\n        subtotal\n        shipping { key description amount taxRate }\n        shippingAdjustments { key description amount taxRate }\n        shippingTotal\n        totalExcludingTax\n        taxes { taxRate base amount }\n        taxIncluded\n        taxTotal\n        rounding\n        total\n        totalBeforeRounding\n        balance { paid giftCard storeCredit credited stillToPay stillToPayNote }\n        reconciles\n";
+export declare const ORDER_MONEY_VIEW_QUERY = "\n  query OrderMoneyView($id: ID!, $basis: OrderMoneyBasis!) {\n    order(id: $id) {\n      id\n      moneyView(basis: $basis) {\n        basis\n        currencyCode\n        lines { orderLineId quantity taxRate unitAmount amount }\n        goodsAdjustments { key description amount taxRate }\n        surcharges { key description amount taxRate }\n        subtotal\n        shipping { key description amount taxRate }\n        shippingAdjustments { key description amount taxRate }\n        shippingTotal\n        totalExcludingTax\n        taxes { taxRate base amount }\n        taxIncluded\n        taxTotal\n        rounding\n        total\n        totalBeforeRounding\n        balance { paid giftCard storeCredit credited stillToPay stillToPayNote }\n        reconciles\n      }\n    }\n  }\n";
+/** `INVALID_ORDER_MONEY_BASIS` for a basis not in `ORDER_MONEY_BASES`, before anything is sent. */
+export declare function assertOrderMoneyBasis(basis: string): asserts basis is OrderMoneyBasis;
+export interface OrderMoneyViewModule {
+    /**
+     * The order's money as rows that add up exactly to its stored totals, in `options.basis`
+     * (default `STORE`). Print these rows as they come, never re-derived: an amount re-computed
+     * from them, or from the order's other figures, can miss the order's own total by a cent.
+     * Needs `ReadOrder`.
+     *
+     * - A unit price (`lines[].unitAmount`) is only answered in the basis the line was priced in;
+     *   show the line total alone in the other.
+     * - The VAT rows are one per rate. On a `GROSS` view they are included in the total
+     *   (`taxIncluded`): label them so, never as an addition.
+     * - `balance.stillToPay` is money not received yet: a bank-transfer or net-terms payment that
+     *   is promised still counts. With `balance.stillToPayNote` answered it reads the B2B account
+     *   ledger; `KEPT_IN_ERP` means print its note, not a figure. Not answered (an older engine,
+     *   resent without it): for an order a live account invoice bills, show the other rows only.
+     * - It reads the order as STORED: it cannot preview an edit (`planEdit`'s `preview.moneyView` does).
+     *
+     * Refused: `INVALID_ORDER_MONEY_BASIS` (`ValidationError`, 400, before sending) for a basis
+     * not in `ORDER_MONEY_BASES`; `ORDER_NOT_FOUND` (`NotFoundError`, 404) for an order this store
+     * does not hold. An engine before `Order.moneyView` refuses the document as
+     * `ValidationError` `GRAPHQL_VALIDATION_FAILED` (400): fall back to the order's own figures.
+     *
+     * @effect read
+     */
+    moneyView(orderId: string, options?: Call & {
+        basis?: OrderMoneyBasis;
+    }): Promise<OrderMoneyView>;
+}
+/** `document` without `stillToPayNote`: what an engine before it accepts. */
+export declare function withoutStillToPayNote(document: string): string;
+/**
+ * The transport, sending a document that names `balance.stillToPayNote` (pricing-display-consistency
+ * B1c) once more without it when the engine refused it as unknown. Safe for a mutation too: a
+ * refused document never ran. The newest money-view field, so it falls away first: wrap it inside
+ * any other `*Aware` transport.
+ */
+export declare function stillToPayNoteAware(transport: Pick<Transport, 'graphql'>): Pick<Transport, 'graphql'>;
+export declare function createOrderMoneyViewModule(transport: Transport): OrderMoneyViewModule;

package/dist/orders/money-view.js

@@ -0,0 +1,99 @@
+/**
+ * `admin.orders.moneyView(orderId, { basis })`: an order's money as rows that add up exactly to
+ * its own totals, in one basis (pricing-display-consistency, USER O12). Every surface that shows
+ * an order's money prints these rows, so an order page, an email and an invoice cannot disagree
+ * by a cent. The engine builds them (`Order.moneyView`); this module only reads them.
+ */
+import { NotFoundError, ValidationError, } from '@sixtyninecommerce/core';
+import { isUnknownFieldRejection } from '../payments/store-credit-fields.js';
+/**
+ * Which prices a view shows. `GROSS` = incl. VAT, `NET` = excl. VAT. `STORE` follows how the
+ * store sets its prices; `CUSTOMER` how the shop shows prices to the order's customer. The view
+ * answers the one it used, `GROSS` or `NET`.
+ */
+export const ORDER_MONEY_BASES = ['STORE', 'CUSTOMER', 'GROSS', 'NET'];
+const ROW_FIELDS = 'key description amount taxRate';
+/** Every field of an `OrderMoneyView`, at every depth: the selection each document reads it with. */
+export const ORDER_MONEY_VIEW_FIELDS = /* GraphQL */ `
+        basis
+        currencyCode
+        lines { orderLineId quantity taxRate unitAmount amount }
+        goodsAdjustments { ${ROW_FIELDS} }
+        surcharges { ${ROW_FIELDS} }
+        subtotal
+        shipping { ${ROW_FIELDS} }
+        shippingAdjustments { ${ROW_FIELDS} }
+        shippingTotal
+        totalExcludingTax
+        taxes { taxRate base amount }
+        taxIncluded
+        taxTotal
+        rounding
+        total
+        totalBeforeRounding
+        balance { paid giftCard storeCredit credited stillToPay stillToPayNote }
+        reconciles
+`;
+export const ORDER_MONEY_VIEW_QUERY = /* GraphQL */ `
+  query OrderMoneyView($id: ID!, $basis: OrderMoneyBasis!) {
+    order(id: $id) {
+      id
+      moneyView(basis: $basis) {${ORDER_MONEY_VIEW_FIELDS}      }
+    }
+  }
+`;
+/** `INVALID_ORDER_MONEY_BASIS` for a basis not in `ORDER_MONEY_BASES`, before anything is sent. */
+export function assertOrderMoneyBasis(basis) {
+    if (!ORDER_MONEY_BASES.includes(basis)) {
+        throw new ValidationError({
+            code: 'INVALID_ORDER_MONEY_BASIS',
+            message: `The basis must be one of ${ORDER_MONEY_BASES.join(', ')}.`,
+            status: 400,
+            service: 'vendure',
+        });
+    }
+}
+const STILL_TO_PAY_NOTE_FIELD = /\bstillToPayNote\b/g;
+/** `document` without `stillToPayNote`: what an engine before it accepts. */
+export function withoutStillToPayNote(document) {
+    return document.replace(STILL_TO_PAY_NOTE_FIELD, '');
+}
+/**
+ * The transport, sending a document that names `balance.stillToPayNote` (pricing-display-consistency
+ * B1c) once more without it when the engine refused it as unknown. Safe for a mutation too: a
+ * refused document never ran. The newest money-view field, so it falls away first: wrap it inside
+ * any other `*Aware` transport.
+ */
+export function stillToPayNoteAware(transport) {
+    return {
+        async graphql(call, options) {
+            try {
+                return await transport.graphql(call, options);
+            }
+            catch (error) {
+                const legacy = withoutStillToPayNote(call.query);
+                if (legacy === call.query || !isUnknownFieldRejection(error))
+                    throw error;
+                return transport.graphql({ ...call, query: legacy }, options);
+            }
+        },
+    };
+}
+export function createOrderMoneyViewModule(transport) {
+    return {
+        async moneyView(orderId, options) {
+            const basis = options?.basis ?? 'STORE';
+            assertOrderMoneyBasis(basis);
+            const data = await stillToPayNoteAware(transport).graphql({ api: 'admin', query: ORDER_MONEY_VIEW_QUERY, variables: { id: orderId, basis } }, options);
+            if (!data.order) {
+                throw new NotFoundError({
+                    code: 'ORDER_NOT_FOUND',
+                    message: `This store has no order ${orderId}.`,
+                    status: 404,
+                    service: 'vendure',
+                });
+            }
+            return data.order.moneyView;
+        },
+    };
+}

package/dist/orders/plan-edit.d.ts

@@ -1,5 +1,6 @@
 import type { Transport } from '@sixtyninecommerce/core';
 import type { Call } from '../types.js';
+import { type OrderMoneyBasis, type OrderMoneyView } from './money-view.js';
 import type { OverpaymentOption } from './surcharges.js';
 /**
  * How a one-time discount is stated. A whole-order discount is `PERCENTAGE` or
@@ -376,6 +377,22 @@ export interface OrderEditPreview {
     taxSummary: OrderEditTaxSummaryLine[];
     /** The order's total with tax before the edit. */
     totalWithTaxBefore: number;
+    /**
+     * The order's money after the edit as the order page prints it once the edit is saved
+     * (`orders.moneyView`'s rows, in `planEdit`'s `moneyBasis`), read inside the preview's run.
+     * Its `balance` is the order's payments before the plan's `refund`. Print these rows, never
+     * the figures above: they are the engine's, before a staff rounding. `null` from an engine
+     * before it; absent from `commitEdit`'s plan (read the saved order's `moneyView`).
+     */
+    moneyView?: OrderMoneyView | null;
+    /** The order's money before the edit, read in the same run, in the same basis. */
+    moneyViewBefore?: OrderMoneyView | null;
+    /**
+     * What the edit changes the billable total by (a staff rounding included):
+     * `moneyView.total - moneyViewBefore.total`, computed by the engine. Print it as the
+     * difference; `totalWithTax - totalWithTaxBefore` ignores the rounding.
+     */
+    totalDifference?: number | null;
 }
 export interface OrderEditPlan {
     orderId: string;
@@ -422,7 +439,12 @@ export interface OrderEditPlan {
  * the order-edit plan, so on an older one this call alone fails validation and
  * no other order call does.
  */
-export declare const PLAN_ORDER_EDIT_QUERY = "\n  query PlanOrderEdit($orderId: ID!, $diff: OrderEditDiffInput!) {\n    planOrderEdit(orderId: $orderId, diff: $diff) {\n      orderId\n      planHash\n      orderVersion\n      steps {\n        kind\n        input\n        moneyEffect\n      }\n      refund {\n        paymentId\n        amount\n      }\n      overpayment {\n        amount\n        currencyCode\n        surchargeIds\n        refund {\n          available\n          code\n          message\n          book\n        }\n        accountCredit {\n          available\n          code\n          message\n          book\n        }\n        refundWhenChosen {\n          paymentId\n          amount\n        }\n      }\n      returnState\n      blockers {\n        code\n        message\n        details\n      }\n      notices {\n        code\n        message\n        details\n      }\n      payment {\n        collected\n        reason\n        method\n      }\n      preview {\n        currencyCode\n        subTotal\n        subTotalWithTax\n        shipping\n        shippingWithTax\n        surcharges\n        surchargesWithTax\n        total\n        totalWithTax\n        taxSummary {\n          description\n          taxRate\n          taxBase\n          taxTotal\n        }\n        totalWithTaxBefore\n      }\n    }\n  }\n";
+export declare const PLAN_ORDER_EDIT_QUERY = "\n  query PlanOrderEdit($orderId: ID!, $diff: OrderEditDiffInput!, $moneyBasis: OrderMoneyBasis!) {\n    planOrderEdit(orderId: $orderId, diff: $diff) {\n      orderId\n      planHash\n      orderVersion\n      steps {\n        kind\n        input\n        moneyEffect\n      }\n      refund {\n        paymentId\n        amount\n      }\n      overpayment {\n        amount\n        currencyCode\n        surchargeIds\n        refund {\n          available\n          code\n          message\n          book\n        }\n        accountCredit {\n          available\n          code\n          message\n          book\n        }\n        refundWhenChosen {\n          paymentId\n          amount\n        }\n      }\n      returnState\n      blockers {\n        code\n        message\n        details\n      }\n      notices {\n        code\n        message\n        details\n      }\n      payment {\n        collected\n        reason\n        method\n      }\n      preview {\n        currencyCode\n        subTotal\n        subTotalWithTax\n        shipping\n        shippingWithTax\n        surcharges\n        surchargesWithTax\n        total\n        totalWithTax\n        taxSummary {\n          description\n          taxRate\n          taxBase\n          taxTotal\n        }\n        totalWithTaxBefore\n        moneyView(basis: $moneyBasis) {\n        basis\n        currencyCode\n        lines { orderLineId quantity taxRate unitAmount amount }\n        goodsAdjustments { key description amount taxRate }\n        surcharges { key description amount taxRate }\n        subtotal\n        shipping { key description amount taxRate }\n        shippingAdjustments { key description amount taxRate }\n        shippingTotal\n        totalExcludingTax\n        taxes { taxRate base amount }\n        taxIncluded\n        taxTotal\n        rounding\n        total\n        totalBeforeRounding\n        balance { paid giftCard storeCredit credited stillToPay stillToPayNote }\n        reconciles\n        }\n        moneyViewBefore(basis: $moneyBasis) {\n        basis\n        currencyCode\n        lines { orderLineId quantity taxRate unitAmount amount }\n        goodsAdjustments { key description amount taxRate }\n        surcharges { key description amount taxRate }\n        subtotal\n        shipping { key description amount taxRate }\n        shippingAdjustments { key description amount taxRate }\n        shippingTotal\n        totalExcludingTax\n        taxes { taxRate base amount }\n        taxIncluded\n        taxTotal\n        rounding\n        total\n        totalBeforeRounding\n        balance { paid giftCard storeCredit credited stillToPay stillToPayNote }\n        reconciles\n        }\n        totalDifference\n      }\n    }\n  }\n";
+/**
+ * The document for an engine before the preview's money view (pricing-display-consistency B3):
+ * the same plan without `moneyView`, `moneyViewBefore`, `totalDifference` and their basis.
+ */
+export declare const PLAN_ORDER_EDIT_QUERY_BEFORE_MONEY_VIEW = "\n  query PlanOrderEdit($orderId: ID!, $diff: OrderEditDiffInput!) {\n    planOrderEdit(orderId: $orderId, diff: $diff) {\n      orderId\n      planHash\n      orderVersion\n      steps {\n        kind\n        input\n        moneyEffect\n      }\n      refund {\n        paymentId\n        amount\n      }\n      overpayment {\n        amount\n        currencyCode\n        surchargeIds\n        refund {\n          available\n          code\n          message\n          book\n        }\n        accountCredit {\n          available\n          code\n          message\n          book\n        }\n        refundWhenChosen {\n          paymentId\n          amount\n        }\n      }\n      returnState\n      blockers {\n        code\n        message\n        details\n      }\n      notices {\n        code\n        message\n        details\n      }\n      payment {\n        collected\n        reason\n        method\n      }\n      preview {\n        currencyCode\n        subTotal\n        subTotalWithTax\n        shipping\n        shippingWithTax\n        surcharges\n        surchargesWithTax\n        total\n        totalWithTax\n        taxSummary {\n          description\n          taxRate\n          taxBase\n          taxTotal\n        }\n        totalWithTaxBefore\n      }\n    }\n  }\n";
 export interface OrderPlanEditModule {
     /**
      * How an edit of a placed order would be carried out, and what the order
@@ -466,6 +488,12 @@ export interface OrderPlanEditModule {
      * Keep `planHash` with what you show: `commitEdit` carries the edit out and
      * names it, so what is saved is what the merchant saw.
      *
+     * Show the edit's money from `preview.moneyView` (after) and `moneyViewBefore`, in
+     * `options.moneyBasis` (default `STORE`; `INVALID_ORDER_MONEY_BASIS` before sending for any
+     * other value than `ORDER_MONEY_BASES`): the same rows the order page prints once the edit is
+     * saved, each promotion, fee, VAT rate and staff rounding its own row. The difference is
+     * `preview.totalDifference`. An engine before them answers the plan without them (`null`).
+     *
      * Refusals of the call:
      * - `ORDER_EDIT_ORDER_NOT_FOUND`, `ORDER_EDIT_LINE_NOT_FOUND`,
      *   `ORDER_EDIT_SURCHARGE_NOT_FOUND` and `ORDER_EDIT_VARIANT_NOT_FOUND`
@@ -483,7 +511,11 @@ export interface OrderPlanEditModule {
      *   was made from the default channel instead of the order's own.
      * - `ORDER_BUSY` (`ConflictError`, 409): another change of the order was
      *   still being applied. Ask again.
+     *
+     * @effect read
      */
-    planEdit(orderId: string, diff: OrderEditDiff, options?: Call): Promise<OrderEditPlan>;
+    planEdit(orderId: string, diff: OrderEditDiff, options?: Call & {
+        moneyBasis?: OrderMoneyBasis;
+    }): Promise<OrderEditPlan>;
 }
 export declare function createOrderPlanEditModule(transport: Transport): OrderPlanEditModule;

package/dist/orders/plan-edit.js

@@ -1,10 +1,91 @@
-import { storeCreditAware } from '../payments/store-credit-fields.js';
+import { isUnknownFieldRejection, storeCreditAware } from '../payments/store-credit-fields.js';
+import { assertOrderMoneyBasis, ORDER_MONEY_VIEW_FIELDS, stillToPayNoteAware, } from './money-view.js';
 /**
  * Its own document on purpose: `planOrderEdit` exists only on an engine with
  * the order-edit plan, so on an older one this call alone fails validation and
  * no other order call does.
  */
 export const PLAN_ORDER_EDIT_QUERY = /* GraphQL */ `
+  query PlanOrderEdit($orderId: ID!, $diff: OrderEditDiffInput!, $moneyBasis: OrderMoneyBasis!) {
+    planOrderEdit(orderId: $orderId, diff: $diff) {
+      orderId
+      planHash
+      orderVersion
+      steps {
+        kind
+        input
+        moneyEffect
+      }
+      refund {
+        paymentId
+        amount
+      }
+      overpayment {
+        amount
+        currencyCode
+        surchargeIds
+        refund {
+          available
+          code
+          message
+          book
+        }
+        accountCredit {
+          available
+          code
+          message
+          book
+        }
+        refundWhenChosen {
+          paymentId
+          amount
+        }
+      }
+      returnState
+      blockers {
+        code
+        message
+        details
+      }
+      notices {
+        code
+        message
+        details
+      }
+      payment {
+        collected
+        reason
+        method
+      }
+      preview {
+        currencyCode
+        subTotal
+        subTotalWithTax
+        shipping
+        shippingWithTax
+        surcharges
+        surchargesWithTax
+        total
+        totalWithTax
+        taxSummary {
+          description
+          taxRate
+          taxBase
+          taxTotal
+        }
+        totalWithTaxBefore
+        moneyView(basis: $moneyBasis) {${ORDER_MONEY_VIEW_FIELDS}        }
+        moneyViewBefore(basis: $moneyBasis) {${ORDER_MONEY_VIEW_FIELDS}        }
+        totalDifference
+      }
+    }
+  }
+`;
+/**
+ * The document for an engine before the preview's money view (pricing-display-consistency B3):
+ * the same plan without `moneyView`, `moneyViewBefore`, `totalDifference` and their basis.
+ */
+export const PLAN_ORDER_EDIT_QUERY_BEFORE_MONEY_VIEW = /* GraphQL */ `
   query PlanOrderEdit($orderId: ID!, $diff: OrderEditDiffInput!) {
     planOrderEdit(orderId: $orderId, diff: $diff) {
       orderId
@@ -80,17 +161,34 @@ export const PLAN_ORDER_EDIT_QUERY = /* GraphQL */ `
 export function createOrderPlanEditModule(transport) {
     return {
         async planEdit(orderId, diff, options) {
-            const data = await storeCreditAware(transport).graphql({
-                api: 'admin',
-                query: PLAN_ORDER_EDIT_QUERY,
-                // The diff goes out as given, never normalised: `orderDiscount` left
-                // out, `null` and a value are three different requests to the engine
-                // (keep, remove, set). `JSON.stringify` drops a key that is
-                // `undefined` and keeps a `null`, so a default here would turn
-                // "keep" into "remove".
-                variables: { orderId, diff },
-            }, options);
-            return data.planOrderEdit;
+            const moneyBasis = options?.moneyBasis ?? 'STORE';
+            assertOrderMoneyBasis(moneyBasis);
+            const send = (query, variables) => storeCreditAware(stillToPayNoteAware(transport)).graphql(
+            // The diff goes out as given, never normalised: `orderDiscount` left
+            // out, `null` and a value are three different requests to the engine
+            // (keep, remove, set). `JSON.stringify` drops a key that is
+            // `undefined` and keeps a `null`, so a default here would turn
+            // "keep" into "remove".
+            { api: 'admin', query, variables: { orderId, diff, ...variables } }, options);
+            try {
+                return (await send(PLAN_ORDER_EDIT_QUERY, { moneyBasis })).planOrderEdit;
+            }
+            catch (error) {
+                // An engine before the preview's money refuses the document before it runs, so
+                // nothing was planned: ask again without it.
+                if (!isUnknownFieldRejection(error))
+                    throw error;
+                const { planOrderEdit } = await send(PLAN_ORDER_EDIT_QUERY_BEFORE_MONEY_VIEW, {});
+                return {
+                    ...planOrderEdit,
+                    preview: planOrderEdit.preview && {
+                        ...planOrderEdit.preview,
+                        moneyView: null,
+                        moneyViewBefore: null,
+                        totalDifference: null,
+                    },
+                };
+            }
         },
     };
 }

package/dist/orders/surcharges.d.ts

@@ -53,6 +53,15 @@ export interface SurchargeRemoveCall extends Call {
      * either (`ORDER_OVERPAYMENT_REFUND_UNRECONCILED`) until it is reconciled.
      */
     overpayment?: OrderOverpaymentChoice;
+    /**
+     * With `ACCOUNT_CREDIT` in a store whose book is store credit (`preview`'s
+     * `accountCredit.book` `STORE_CREDIT`): whether the customer expressly agreed to store credit
+     * instead of a refund to their payment (EU consumer law, CRD art. 13(1)), as staff recorded it.
+     * The move records it on its ledger entries (`StoredValueEntry.customerAgreed`); never a
+     * condition, nothing is refused for it, and it is recorded nowhere else. Sent only when given;
+     * an engine before the field (incentives sprint 8 PR 6a) refuses a call that gives it.
+     */
+    customerAgreed?: boolean;
 }
 /** Options for a surcharge write. */
 export interface SurchargeCall extends SurchargeRemoveCall {
@@ -197,5 +206,8 @@ export declare const UPDATE_ORDER_SURCHARGE_MUTATION = "\n  mutation UpdateOrder
 export declare const UPDATE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION = "\n  mutation UpdateOrderSurchargeWithOverpayment(\n    $orderId: ID!\n    $surchargeId: ID!\n    $input: SurchargeInput!\n    $taxClass: String\n    $idempotencyKey: String\n    $overpayment: OrderOverpaymentChoice\n  ) {\n    updateOrderSurcharge(\n      orderId: $orderId\n      surchargeId: $surchargeId\n      input: $input\n      taxClass: $taxClass\n      idempotencyKey: $idempotencyKey\n      overpayment: $overpayment\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
 export declare const REMOVE_ORDER_SURCHARGE_MUTATION = "\n  mutation RemoveOrderSurcharge($orderId: ID!, $surchargeId: ID!, $idempotencyKey: String) {\n    removeOrderSurcharge(\n      orderId: $orderId\n      surchargeId: $surchargeId\n      idempotencyKey: $idempotencyKey\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
 export declare const REMOVE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION = "\n  mutation RemoveOrderSurchargeWithOverpayment(\n    $orderId: ID!\n    $surchargeId: ID!\n    $idempotencyKey: String\n    $overpayment: OrderOverpaymentChoice\n  ) {\n    removeOrderSurcharge(\n      orderId: $orderId\n      surchargeId: $surchargeId\n      idempotencyKey: $idempotencyKey\n      overpayment: $overpayment\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
+export declare const ADD_ORDER_SURCHARGE_WITH_CONSENT_MUTATION: string;
+export declare const UPDATE_ORDER_SURCHARGE_WITH_CONSENT_MUTATION: string;
+export declare const REMOVE_ORDER_SURCHARGE_WITH_CONSENT_MUTATION: string;
 export declare const PREVIEW_ORDER_SURCHARGE_CHANGE_QUERY = "\n  query PreviewOrderSurchargeChange($orderId: ID!, $change: OrderSurchargeChangeInput!) {\n    previewOrderSurchargeChange(orderId: $orderId, change: $change) {\n      currencyCode\n      totalBefore\n      totalAfter\n      overpayment {\n        amount\n        currencyCode\n        refund { available code message book }\n        accountCredit { available code message book }\n      }\n    }\n  }\n";
 export declare function createSurchargesModule(transport: Transport): SurchargesModule;

package/dist/orders/surcharges.js

@@ -1,3 +1,4 @@
+import { customerAgreedVariable, withCustomerAgreed } from '../payments/customer-consent.js';
 import { storeCreditAware } from '../payments/store-credit-fields.js';
 const SURCHARGED_ORDER_FIELDS = /* GraphQL */ `
   id
@@ -121,6 +122,15 @@ export const REMOVE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION = /* GraphQL */ `
     }
   }
 `;
+// A third document per write, used only on a call that states the customer's answer to store
+// credit: an engine before the argument still takes every call that does not.
+const CONSENT_ANCHOR = {
+    declaration: '$overpayment: OrderOverpaymentChoice',
+    argument: 'overpayment: $overpayment',
+};
+export const ADD_ORDER_SURCHARGE_WITH_CONSENT_MUTATION = withCustomerAgreed(ADD_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION, CONSENT_ANCHOR);
+export const UPDATE_ORDER_SURCHARGE_WITH_CONSENT_MUTATION = withCustomerAgreed(UPDATE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION, CONSENT_ANCHOR);
+export const REMOVE_ORDER_SURCHARGE_WITH_CONSENT_MUTATION = withCustomerAgreed(REMOVE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION, CONSENT_ANCHOR);
 const OVERPAYMENT_OPTION_FIELDS = 'available code message book';
 export const PREVIEW_ORDER_SURCHARGE_CHANGE_QUERY = /* GraphQL */ `
   query PreviewOrderSurchargeChange($orderId: ID!, $change: OrderSurchargeChangeInput!) {
@@ -142,6 +152,12 @@ function overpaymentVariable(options) {
     const value = options?.overpayment;
     return value === 'REFUND' || value === 'ACCOUNT_CREDIT' ? value : undefined;
 }
+/** The document a write sends: the plainest one that declares every argument the call states. */
+function surchargeDocument(options, documents) {
+    if (customerAgreedVariable(options?.customerAgreed) !== undefined)
+        return documents.consent;
+    return overpaymentVariable(options) === undefined ? documents.plain : documents.overpayment;
+}
 /**
  * `undefined` rather than `null` for an absent tax class: a variable explicitly
  * set to null is still a value the engine reads, and this argument's whole
@@ -156,15 +172,18 @@ export function createSurchargesModule(transport) {
         async add(orderId, input, options) {
             const data = await transport.graphql({
                 api: 'admin',
-                query: overpaymentVariable(options) === undefined
-                    ? ADD_ORDER_SURCHARGE_MUTATION
-                    : ADD_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION,
+                query: surchargeDocument(options, {
+                    plain: ADD_ORDER_SURCHARGE_MUTATION,
+                    overpayment: ADD_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION,
+                    consent: ADD_ORDER_SURCHARGE_WITH_CONSENT_MUTATION,
+                }),
                 variables: {
                     orderId,
                     input,
                     taxClass: taxClassVariable(options),
                     idempotencyKey: options?.idempotencyKey,
                     overpayment: overpaymentVariable(options),
+                    customerAgreed: customerAgreedVariable(options?.customerAgreed),
                 },
             }, options);
             return data.addOrderSurcharge;
@@ -172,9 +191,11 @@ export function createSurchargesModule(transport) {
         async update(orderId, surchargeId, input, options) {
             const data = await transport.graphql({
                 api: 'admin',
-                query: overpaymentVariable(options) === undefined
-                    ? UPDATE_ORDER_SURCHARGE_MUTATION
-                    : UPDATE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION,
+                query: surchargeDocument(options, {
+                    plain: UPDATE_ORDER_SURCHARGE_MUTATION,
+                    overpayment: UPDATE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION,
+                    consent: UPDATE_ORDER_SURCHARGE_WITH_CONSENT_MUTATION,
+                }),
                 variables: {
                     orderId,
                     surchargeId,
@@ -182,6 +203,7 @@ export function createSurchargesModule(transport) {
                     taxClass: taxClassVariable(options),
                     idempotencyKey: options?.idempotencyKey,
                     overpayment: overpaymentVariable(options),
+                    customerAgreed: customerAgreedVariable(options?.customerAgreed),
                 },
             }, options);
             return data.updateOrderSurcharge;
@@ -189,14 +211,17 @@ export function createSurchargesModule(transport) {
         async remove(orderId, surchargeId, options) {
             const data = await transport.graphql({
                 api: 'admin',
-                query: overpaymentVariable(options) === undefined
-                    ? REMOVE_ORDER_SURCHARGE_MUTATION
-                    : REMOVE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION,
+                query: surchargeDocument(options, {
+                    plain: REMOVE_ORDER_SURCHARGE_MUTATION,
+                    overpayment: REMOVE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION,
+                    consent: REMOVE_ORDER_SURCHARGE_WITH_CONSENT_MUTATION,
+                }),
                 variables: {
                     orderId,
                     surchargeId,
                     idempotencyKey: options?.idempotencyKey,
                     overpayment: overpaymentVariable(options),
+                    customerAgreed: customerAgreedVariable(options?.customerAgreed),
                 },
             }, options);
             return data.removeOrderSurcharge;

package/dist/payments/account-credit.d.ts

@@ -56,6 +56,17 @@ export interface CreditOverpaymentInput {
     /** Why, in your own words: shown on the receipt and in the order's history. */
     reason?: string;
 }
+/** Options of {@link AccountCreditModule.creditOverpaymentToStoreCredit}. */
+export interface CreditOverpaymentToStoreCreditCall extends Call {
+    /**
+     * Whether the customer expressly agreed to store credit instead of a refund to their payment
+     * (EU consumer law, CRD art. 13(1)), as staff recorded it: the move records it on its ledger
+     * entries (`StoredValueEntry.customerAgreed`). Never a condition, nothing is refused for it.
+     * Part of the request: a repeat under the same key sends the same answer. Sent only when given;
+     * an engine before the argument (incentives sprint 8 PR 6a) refuses a call that gives it.
+     */
+    customerAgreed?: boolean;
+}
 export interface ApplyUnappliedCashInput {
     unappliedCashId: string;
     /** The AR invoice to pay. Give exactly one of `invoiceId` and `orderId`. */
@@ -151,7 +162,7 @@ export interface AccountCreditModule {
      * it off `refundable` and `payments.position` no longer reports it as `overpaid`. Needs an
      * engine with incentives sprint 8 PR 3.
      */
-    creditOverpaymentToStoreCredit(input: CreditOverpaymentInput, options?: Call): Promise<StoreCreditMove>;
+    creditOverpaymentToStoreCredit(input: CreditOverpaymentInput, options?: CreditOverpaymentToStoreCreditCall): Promise<StoreCreditMove>;
     /** A customer's unapplied cash in this store, oldest first. */
     list(customerId: string, options?: Call): Promise<UnappliedCash[]>;
     /**
@@ -189,6 +200,11 @@ export interface AccountCreditModule {
 }
 export declare const CREDIT_ORDER_OVERPAYMENT_MUTATION = "\n  mutation CreditOrderOverpaymentToAccount(\n    $input: CreditOrderOverpaymentInput!\n    $idempotencyKey: String\n  ) {\n    creditOrderOverpaymentToAccount(input: $input, idempotencyKey: $idempotencyKey) {\n      \n  id\n  customerId\n  currencyCode\n  amount\n  applied\n  refunded\n  remaining\n  orderId\n  paymentId\n  receivedOn\n  reference\n  notes\n  createdAt\n\n    }\n  }\n";
 export declare const CREDIT_ORDER_OVERPAYMENT_TO_STORE_CREDIT_MUTATION = "\n  mutation CreditOrderOverpaymentToStoreCredit(\n    $input: CreditOrderOverpaymentInput!\n    $idempotencyKey: String\n  ) {\n    creditOrderOverpaymentToStoreCredit(input: $input, idempotencyKey: $idempotencyKey) {\n      accountId amount currencyCode entryIds\n    }\n  }\n";
+/**
+ * The same, declaring the customer's answer to store credit: sent only by a call that states it,
+ * so an engine before the argument still takes every call that does not.
+ */
+export declare const CREDIT_ORDER_OVERPAYMENT_TO_STORE_CREDIT_WITH_CONSENT_MUTATION = "\n  mutation CreditOrderOverpaymentToStoreCredit(\n    $input: CreditOrderOverpaymentInput!\n    $idempotencyKey: String\n    $customerAgreed: Boolean\n  ) {\n    creditOrderOverpaymentToStoreCredit(\n      input: $input\n      idempotencyKey: $idempotencyKey\n      customerAgreed: $customerAgreed\n    ) {\n      accountId amount currencyCode entryIds\n    }\n  }\n";
 export declare const UNAPPLIED_CASH_QUERY = "\n  query ArUnappliedCash($customerId: ID!) {\n    arUnappliedCash(customerId: $customerId) {\n      \n  id\n  customerId\n  currencyCode\n  amount\n  applied\n  refunded\n  remaining\n  orderId\n  paymentId\n  receivedOn\n  reference\n  notes\n  createdAt\n\n    }\n  }\n";
 export declare const APPLY_UNAPPLIED_CASH_MUTATION = "\n  mutation ApplyArUnappliedCash($input: ApplyArUnappliedCashInput!, $idempotencyKey: String) {\n    applyArUnappliedCash(input: $input, idempotencyKey: $idempotencyKey) {\n      \n  id\n  customerId\n  currencyCode\n  amount\n  applied\n  refunded\n  remaining\n  orderId\n  paymentId\n  receivedOn\n  reference\n  notes\n  createdAt\n\n    }\n  }\n";
 export declare const REFUND_UNAPPLIED_CASH_MUTATION = "\n  mutation RefundArUnappliedCash($input: RefundArUnappliedCashInput!, $idempotencyKey: String) {\n    refundArUnappliedCash(input: $input, idempotencyKey: $idempotencyKey) {\n      id\n      total\n      state\n      method\n      transactionId\n      reason\n    }\n  }\n";