@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/meta/index.d.ts

@@ -39,6 +39,11 @@ export interface MetaCatalogLabels {
     auditCallOutcome: LabelMap;
     /** Who sends a notification event's email: `platform` or `none` (`admin.tenant.notifications`). */
     notificationSender: LabelMap;
+    /**
+     * A supplier purchase order's status (`admin.purchasing.purchaseOrders`). Served by a platform
+     * with purchase orders; absent before.
+     */
+    purchaseOrderStatus?: LabelMap;
     /**
      * A vocabulary added after this SDK release arrives camelised, with its map
      * untouched.
@@ -54,6 +59,12 @@ export interface MetaCatalogTransitions {
      * UNRANKED, so it is absent — treat "no rank" as "no forward move", never 0.
      */
     fulfillmentRank: Record<string, number>;
+    /**
+     * A supplier purchase order's lifecycle (`admin.purchasing.purchaseOrders`): `cancelled` is
+     * terminal, `closed` moves only back to `sent`. Served by a platform with purchase orders;
+     * absent before.
+     */
+    purchaseOrder?: TransitionMap;
     [extra: string]: unknown;
 }
 export interface PermissionGroup {
@@ -108,6 +119,12 @@ export interface MetaCatalogPermissions {
 export interface PluginCatalogEntry {
     key: string;
     name: string;
+    /**
+     * One sentence on what the plugin does, in merchant English: the words the
+     * platform's own dashboard shows beside the name. Served by a platform from
+     * this release on.
+     */
+    description: string;
     group: string;
     /** `system` plugins are always on; `external` ones need an entitlement. */
     kind: string;
@@ -117,6 +134,142 @@ export interface MetaCatalogPlugins {
     groupLabels: Record<string, string>;
     [extra: string]: unknown;
 }
+/** Which API a plugin settings input is written through. */
+export type PluginConfigWriteApi = 'admin-graphql' | 'plugins-rest';
+/**
+ * How a secret property of a plugin settings schema behaves on READ, carried
+ * as the schema property's `x-secret` keyword beside `writeOnly: true`:
+ *
+ * - `masked-roundtrip`: the config read returns a masked preview (named in
+ *   {@link PluginConfigRead.fields}); sending that preview back unchanged, or
+ *   leaving the property out, keeps the stored secret. A BLANK is not the same
+ *   everywhere: it keeps the Tikkie credentials but REMOVES the till's Mollie
+ *   key, so read the property's `description` before sending one;
+ * - `write-only`: no value the read returns may be sent back. A masked preview
+ *   may exist for display, but the platform would store it AS the secret, so
+ *   never pre-fill the field;
+ * - `server-generated`: the platform mints it; a head shows it, never asks for it.
+ */
+export type PluginConfigSecret = 'masked-roundtrip' | 'write-only' | 'server-generated';
+/** The operation that writes a settings input. */
+export interface PluginConfigWrite {
+    api: PluginConfigWriteApi;
+    /** The Admin API mutation (`admin-graphql`), or `METHOD /path` on the plugins service. */
+    operation: string;
+    /**
+     * The mutation argument that takes the input type named by
+     * {@link PluginConfigInput.name}, e.g. `input`. Absent when the mutation takes
+     * its settings as INLINE arguments (then `name` is the operation itself and the
+     * schema's properties are the argument names), and absent for a REST body.
+     */
+    argument?: string;
+    /**
+     * The field of the argument's input object that takes the schema's
+     * properties, when they are only PART of a wider input: the SEO plugin's
+     * Channel defaults go in `updateChannel(input: { id, customFields: { … } })`
+     * under `customFields`. That schema lists only its own fields and stays open
+     * to the rest (other forms' fields), and {@link key} is then a field of the
+     * argument object (`input.id`). Absent: the argument IS the input. Served by a
+     * platform from this release on.
+     */
+    field?: string;
+    /**
+     * For a plugin whose settings are a COLLECTION of records (email gateways,
+     * product feeds): what names the record this input changes. The mutation
+     * argument sent beside {@link argument} (`updateEmailGateway(id:, input:)`);
+     * with {@link field}, a field of the argument object; for a REST write, the
+     * path parameter of `operation` (`PATCH /feeds/configs/:id` → `id`). Absent
+     * for a create and for settings that are one record per store, and for an
+     * input that names its record by a property of its own (`paymentMethodCode`,
+     * which {@link PluginConfigRead.fields} pre-fills). Served by a platform from
+     * this release on.
+     */
+    key?: string;
+}
+/** The read that pre-fills a form for this input. */
+export interface PluginConfigRead {
+    /** The Admin API query (or `GET /path`) that returns the stored config. */
+    operation: string;
+    /**
+     * The field of the read's answer that holds {@link fields}, when they are
+     * nested: `activeChannel { customFields { … } }` → `customFields`. Absent: the
+     * answer itself holds them. Served by a platform from this release on.
+     */
+    field?: string;
+    /** The permission the read needs; not always the write's. */
+    permission: string;
+    /**
+     * EVERY permission that allows the read, {@link permission} first, when there
+     * is more than one: holding any one of them is enough. Absent when
+     * `permission` is the only one, so read `permissions ?? [permission]`. Served
+     * by a platform from this release on.
+     */
+    permissions?: string[];
+    /**
+     * For a collection: the query argument (for a REST read, the path parameter
+     * of {@link operation}) that names the record to read, e.g. `id`. Served by a
+     * platform from this release on.
+     */
+    key?: string;
+    /**
+     * For a collection: the query that lists every record. Each item reads like
+     * {@link operation}'s answer, and its field named like {@link key} is the
+     * value {@link key} takes (`id`; `paymentMethodCode` for a payment provider).
+     * A REST list is `GET /path` answering a cursor page: the items in `data`, the
+     * next page through `pagination.next_cursor`. Served by a platform from this
+     * release on.
+     */
+    list?: string;
+    /**
+     * Schema property → the field of the read that pre-fills it, keyed by DATA
+     * (the schema's own property names). A property absent here has nothing to
+     * pre-fill: a write-only secret, or a value the read does not return. A read
+     * field that is null pre-fills nothing either: leave the property out, which
+     * keeps the stored value. Projected that way, a read validates against the
+     * schema once any required write-only secret is typed in. For a
+     * `plugins-rest` input both sides are the route's WIRE names
+     * (`language_code`); this SDK's typed modules over those routes
+     * (`admin.feeds.get`) camelise top-level keys, so map them back, or call the
+     * route in wire form.
+     */
+    fields: Record<string, string>;
+}
+/** One settings input of a plugin: what to send, where, and who may send it. */
+export interface PluginConfigInput {
+    /**
+     * The GraphQL input type (or REST DTO) the schema describes, e.g.
+     * `UpdateHendriksConfigInput`; for a mutation that takes inline arguments
+     * (`write.argument` absent), the operation itself, e.g. `setMyparcelEnabled`.
+     */
+    name: string;
+    write: PluginConfigWrite;
+    /** `null` when no read returns this input's values. */
+    read: PluginConfigRead | null;
+    /** The permission the write needs on the active store. */
+    permission: string;
+    /**
+     * EVERY permission that allows the write, {@link permission} first, when there
+     * is more than one: holding any one of them is enough (POS receipt numbering
+     * takes `UpdateSettings` or `ManagePosDevices`). Absent when `permission` is
+     * the only one, so read `permissions ?? [permission]`. Served by a platform
+     * from this release on.
+     */
+    permissions?: string[];
+    /**
+     * Draft 2020-12 JSON Schema of the input. It states only what the platform
+     * enforces on write: schema-valid means "worth sending", not "certain to be
+     * accepted" (a refusal can depend on stored state, e.g. enabling before a
+     * credential exists). Property names are the API's own and are never
+     * camelised. A secret carries `writeOnly: true` and `x-secret`. A write the
+     * platform deprecates (the legacy Mollie/Stripe key door) carries the
+     * standard `deprecated: true`.
+     */
+    schema: JsonSchema;
+}
+/** Every settings input one plugin takes. */
+export interface PluginConfigSchemas {
+    inputs: PluginConfigInput[];
+}
 export interface MetaCatalog {
     /**
      * A short hash of everything else. It changes only when the catalog's content
@@ -138,6 +291,15 @@ export interface MetaCatalog {
      * shape.
      */
     settingsSchemas: Record<string, JsonSchema>;
+    /**
+     * JSON Schema of each plugin's settings inputs, keyed by PLUGIN KEY
+     * (`payment-links`, `external-tracking`, …, as in `plugins.catalog`), so a
+     * head can render a plugin's settings form from data. Everything below the
+     * plugin key, the schemas included, arrives exactly as the platform spells
+     * it. A plugin with no entry has no per-store settings at all (search,
+     * warehouse, stored value). Served by a platform from this release on.
+     */
+    pluginConfigSchemas: Record<string, PluginConfigSchemas>;
     /**
      * A member added after this SDK release arrives with its NAME camelised and
      * its contents untouched — the half that matters, since a member this build

package/dist/orders/cancel-with-money.d.ts

@@ -0,0 +1,227 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { StoreCreditMove } from '../payments/account-credit.js';
+import type { IssuedRefund, OrderPaymentPosition, PaidOrder } from '../payments/index.js';
+import type { Call } from '../types.js';
+import type { OrderOverpaymentChoice, OverpaymentOption } from './surcharges.js';
+/** What happens to the money an order holds when it is cancelled. Pass one, or neither. */
+export interface CancelWithMoneyCall extends Call {
+    /**
+     * Why the order is cancelled. REQUIRED with `retain`, where it is recorded in the order's
+     * history and the audit trail; otherwise written on the refunds and the account credit. At
+     * most 500 characters.
+     */
+    reason?: string;
+    /**
+     * The settled money goes back: `REFUND` to the payments it came from, or `ACCOUNT_CREDIT` to
+     * the customer's account (only where the store keeps the customer's balance itself). Ignored
+     * when the order holds no settled money.
+     */
+    overpayment?: OrderOverpaymentChoice;
+    /** The settled money stays on the cancelled order (with a `reason`). */
+    retain?: boolean;
+}
+/** What a cancel with a money decision did. */
+/**
+ * How a refund's money reaches the customer: `PROVIDER` (the payment provider pays it back; the
+ * refund stays `Pending` until it confirms), `AUTOMATIC` (the platform puts it back itself: a
+ * stored-value refund credits the gift card or store credit it was paid with), `MANUAL` (an
+ * offline method: the refund is recorded and staff pay it out by hand). Only a `MANUAL` refund
+ * needs anyone to move money.
+ */
+export type OrderCancelMoneyPayout = 'PROVIDER' | 'AUTOMATIC' | 'MANUAL';
+/** How one refund a cancel made reaches the customer. */
+export interface OrderCancelRefundPayout {
+    refundId: string;
+    paymentId: string;
+    payout: OrderCancelMoneyPayout;
+}
+export interface OrderCancellation {
+    /** The order as the cancel left it (`state: 'Cancelled'`). */
+    order: PaidOrder;
+    /**
+     * The refunds the cancel made: a card refund stays `Pending` until the payment provider
+     * confirms it; one recorded (an offline method, or stored value) is `Settled`. Which ones
+     * staff pay out by hand is `refundPayouts`.
+     */
+    refunds: IssuedRefund[];
+    /** Minor units the store kept on the cancelled order (`retain`); 0 otherwise. */
+    retained: number;
+    /** How each refund in `refunds` reaches the customer, by refund id. */
+    refundPayouts: OrderCancelRefundPayout[];
+    /** Minor units the cancel moved to the customer's account (`ACCOUNT_CREDIT`); 0 otherwise. */
+    creditedToAccount: number;
+    /**
+     * Minor units the cancel moved to the customer's store credit (`ACCOUNT_CREDIT` in a store
+     * whose book is store credit); 0 otherwise, and from an engine before it. Beside
+     * `creditedToAccount`, never part of it. Such a cancel also refunds its gift-card and
+     * store-credit payments to their own balances (`refunds`, payout `AUTOMATIC`).
+     */
+    creditedToStoreCredit: number;
+    /** The move to the customer's store-credit wallet; null otherwise. */
+    storeCredit: StoreCreditMove | null;
+    /** The card holds the cancel voided. */
+    voidedHolds: OrderCancelMoneyHold[];
+    /**
+     * The order's payment position after the cancel, with what of its money is now on the
+     * customer's account (`creditedToAccount`, already taken off `settled`).
+     */
+    position: OrderPaymentPosition & {
+        creditedToAccount: number;
+    };
+}
+/** A card hold `cancelWithMoney` voids, whatever is decided. Minor units. */
+export interface OrderCancelMoneyHold {
+    paymentId: string;
+    method: string | null;
+    amount: number;
+}
+/** A refund `cancelWithMoney` makes on `REFUND`: everything one settled payment holds. */
+export interface OrderCancelMoneyRefund {
+    paymentId: string;
+    method: string | null;
+    /** Minor units. */
+    amount: number;
+    /** How its money reaches the customer: only a `MANUAL` refund is paid out by hand. */
+    payout: OrderCancelMoneyPayout;
+}
+/**
+ * What `cancelWithMoney` would do with the money an order holds (`previewCancelWithMoney`), read
+ * now: each way of deciding, open or with the refusal the cancel would answer for it. Nothing was
+ * written and no lock was taken: the cancel judges it all again.
+ */
+export interface OrderCancelMoneyPreview {
+    orderId: string;
+    currencyCode: string;
+    /**
+     * What the order's settled payments still hold, minor units: what `REFUND` gives back,
+     * `ACCOUNT_CREDIT` moves, or `retain` keeps. 0 when no decision is needed (a decision is then
+     * ignored).
+     */
+    settledHeld: number;
+    /**
+     * What gift cards sold on the order hold of its settled payments, minor units, beside
+     * `settledHeld` (never part of it): the value of a card already spent, which stays with the
+     * store, or of a card still live. No refund or account credit gives it back: only `retain` keeps
+     * it, with `settledHeld`, and while it is above 0 `REFUND` and `ACCOUNT_CREDIT` are closed
+     * (`REFUND_HELD_BY_GIFT_CARD`). A decision is needed when `settledHeld + giftCardHeld` is above 0;
+     * `retain` keeps that sum.
+     */
+    giftCardHeld: number;
+    /** The card holds the cancel voids, whatever is decided. */
+    holds: OrderCancelMoneyHold[];
+    /** The refunds `REFUND` would make, the recorded ones first. Empty while it is closed. */
+    refunds: OrderCancelMoneyRefund[];
+    /** `overpayment: 'REFUND'`: open, or the refusal choosing it would answer. */
+    refund: OverpaymentOption;
+    /**
+     * `overpayment: 'ACCOUNT_CREDIT'`: open only where the store keeps the customer's balance itself
+     * and the customer has a credit account there; otherwise the account's own refusal
+     * (`AR_LEDGER_NOT_ENABLED`, `AR_ACCOUNT_REQUIRED`, `AR_ACCOUNT_IN_ERP`, `ACCOUNT_CREDIT_*`, …).
+     */
+    accountCredit: OverpaymentOption;
+    /** `retain: true` (with a `reason`): open, or the refusal choosing it would answer. */
+    retain: OverpaymentOption;
+    /**
+     * The refusal the cancel answers whatever is decided (`ORDER_OVERPAYMENT_REFUND_UNRECONCILED`,
+     * `ORDER_CANCEL_HOLD_NOT_RELEASABLE`, `ORDER_CANCEL_SETTLEMENT_SPLIT` over two card holds,
+     * `REFUND_METHOD_UNAVAILABLE` for a hold), in the cancel's own words; null while a decision is
+     * open.
+     */
+    refusal: {
+        code: string;
+        message: string;
+    } | null;
+    /** The order's payment position, with what of its money is on the customer's account. */
+    position: OrderPaymentPosition & {
+        creditedToAccount: number;
+    };
+}
+/**
+ * Its own document, like the cancel's: on an engine without the query this call alone fails
+ * validation.
+ */
+export declare const CANCEL_ORDER_WITH_MONEY_PREVIEW_QUERY = "\n  query CancelOrderWithMoneyPreview($orderId: ID!) {\n    cancelOrderWithMoneyPreview(orderId: $orderId) {\n      orderId\n      currencyCode\n      settledHeld\n      giftCardHeld\n      holds {\n        paymentId\n        method\n        amount\n      }\n      refunds {\n        paymentId\n        method\n        amount\n        payout\n      }\n      refund { \n  available\n  code\n  message\n  book\n }\n      accountCredit { \n  available\n  code\n  message\n  book\n }\n      retain { \n  available\n  code\n  message\n  book\n }\n      refusal {\n        code\n        message\n      }\n      position {\n        total\n        covered\n        settled\n        authorized\n        refunded\n        creditedToAccount\n        creditNoted\n        owed\n        outstanding\n        overpaid\n        availableToCharge\n      }\n    }\n  }\n";
+/**
+ * Its own document on purpose: `cancelOrderWithMoney` exists only on an engine that serves it,
+ * so on an older one this call alone fails validation and no other order call does.
+ */
+export declare const CANCEL_ORDER_WITH_MONEY_MUTATION = "\n  mutation CancelOrderWithMoney($input: CancelOrderWithMoneyInput!, $idempotencyKey: String) {\n    cancelOrderWithMoney(input: $input, idempotencyKey: $idempotencyKey) {\n      order {\n        id\n        code\n        state\n        currencyCode\n        total\n        totalWithTax\n      }\n      refunds {\n        id\n        total\n        state\n        method\n        transactionId\n        reason\n      }\n      retained\n      refundPayouts {\n        refundId\n        paymentId\n        payout\n      }\n      creditedToAccount\n      creditedToStoreCredit\n      storeCredit { accountId amount currencyCode entryIds }\n      voidedHolds {\n        paymentId\n        method\n        amount\n      }\n      position {\n        total\n        covered\n        settled\n        authorized\n        refunded\n        creditedToAccount\n        creditNoted\n        owed\n        outstanding\n        overpaid\n        availableToCharge\n      }\n    }\n  }\n";
+export interface OrderCancelWithMoneyModule {
+    /**
+     * Cancel a whole order, its shipping included (a cancelled order bills nothing), and decide,
+     * in the same transaction, what happens to the money it holds. Needs `UpdateOrder`. The
+     * cancel's own rules are the order page's: a fulfillment
+     * holding a line refuses it, and a shopper's live cart is cancelled only when it carries a
+     * payment or a stock movement. It is the one way to cancel a `Parked` order: straight out of
+     * the park, its reserved stock released, with no `order.unparked`.
+     *
+     * Settled money goes back by `overpayment: 'REFUND'` (every payment that holds some, whole)
+     * or `'ACCOUNT_CREDIT'`, or stays with `retain: true` and a `reason`. A card hold on a gateway
+     * is voided whatever the choice; capture it first (`settlePayment`) to keep that money.
+     *
+     * A plain cancel (`cancelOrder` on the Admin API, or `orders.bulk` with `CANCEL`) of an order
+     * that has been placed or parked and still holds money is refused `ORDER_HOLDS_MONEY`
+     * (`BusinessRuleError`, 422), with `extensions.position` and `extensions.refundPosition`:
+     * cancel it here instead, or give the money back first (refund each settled payment with
+     * `payments.refund`, cancel a card hold's payment) and then cancel. What gift cards sold on the
+     * order hold (`giftCardHeld`) is never given back: only `retain` here keeps it.
+     *
+     * Refusals, with nothing written:
+     * - `ORDER_CANCEL_MONEY_CHOICE_REQUIRED` (422): settled money and no decision.
+     * - `CANCEL_RETAIN_REASON_REQUIRED` (422), `ORDER_CANCEL_MONEY_INPUT_INVALID`
+     *   (`ValidationError`, 400: both a choice and `retain`, or a reason over 500 characters).
+     * - `ORDER_CANCEL_SETTLEMENT_SPLIT` (422): more than one card payment to refund or void. The
+     *   cancel asks a payment provider at most once, as its last step: refund or void all but one
+     *   first (`payments.refund`; release a card hold at the payment provider first where its
+     *   payment method cannot), then cancel. A hold its method cannot release answers
+     *   `ORDER_CANCEL_HOLD_NOT_RELEASABLE` instead, whatever else the order holds.
+     * - `ORDER_CANCEL_HOLD_NOT_RELEASABLE` (422, `extensions.paymentId`, `extensions.method`): a card
+     *   hold whose payment method cannot void an authorization at its provider (cancelling it here
+     *   would mark it cancelled while the provider keeps the money reserved). Release the hold at
+     *   the payment provider first, then cancel that payment on the order, then cancel the order.
+     * - `ORDER_OVERPAYMENT_REFUND_UNRECONCILED` (422): a refund of unknown outcome is open; record
+     *   the provider's answer first (`payments.reconcileRefund`).
+     * - `REFUND_HELD_BY_GIFT_CARD` (422, with `extensions.refundPosition`): `overpayment` while gift
+     *   cards sold on the order hold part of its settled money (`giftCardHeld` on the preview).
+     *   Neither way gives that back, and the cancel settles all of the money or none: refund the
+     *   rest first (`payments.refund`), then cancel with `retain` and a `reason`, which keeps the
+     *   gift cards' share on the cancelled order and records it.
+     * - `REFUND_METHOD_UNAVAILABLE`, the account's own refusals (`ACCOUNT_CREDIT_*`, `AR_*`), and
+     *   the cancel's (`ORDER_HAS_ACTIVE_FULFILLMENT`, `ORDER_UNITS_SHIPPED`,
+     *   `ORDER_CART_NOT_CANCELLABLE`, and `LOCATION_OUT_OF_SCOPE` for a credential restricted to
+     *   stock locations while the order's stock is reserved outside them).
+     * - `ORDER_CANCEL_REFUSED`: the engine refused the cancel itself (an order already cancelled
+     *   included), or the void of a card hold was not confirmed and recorded: the provider refused
+     *   it, did not answer (an app's cancel hook that never answered included), or answered and the
+     *   engine could not record it. NOTHING is cancelled either way, but the key differs: an engine
+     *   refusal is stored and a repeat under the same key answers it again, so clear the condition
+     *   and cancel again under a NEW key; a void that was not confirmed releases the key, so a retry
+     *   under it asks the provider again. After a void, the hold may or may not still stand: check
+     *   it at the provider (void or capture it there if it does), then cancel again.
+     * - `PAYMENT_CANCEL_CONFLICT` (`ConflictError`, 409, `extensions.state`): the engine refused the
+     *   void before asking the provider: the payment moved since the cancel read it, or a capture
+     *   of it may have reached its provider. Nothing was asked and NOTHING is cancelled; read the
+     *   order again and act on it as it stands.
+     *
+     * `IDEMPOTENCY_OUTCOME_UNKNOWN` (`error.outcomeUnknown`, `extensions.movement`): the refund
+     * reached the payment provider and its answer never came. NOTHING is cancelled; the attempt is
+     * recorded and reserved on the order, and the key stays spent for 24 hours. Record the
+     * provider's answer (`payments.reconcileRefund`), then cancel again under a NEW key: a refund
+     * recorded as made is not made a second time.
+     *
+     * `idempotencyKey`: a repeat under it answers the first call's result, never a second cancel.
+     */
+    cancelWithMoney(orderId: string, options?: CancelWithMoneyCall): Promise<OrderCancellation>;
+    /**
+     * What {@link cancelWithMoney} would do with the money the order holds, before staff decide:
+     * what its settled payments hold (`settledHeld`, and beside it `giftCardHeld`, what gift cards
+     * sold on the order hold, which only `retain` keeps), the card holds it voids, the refunds
+     * `REFUND` would make,
+     * and for each way (`REFUND`, `ACCOUNT_CREDIT`, `retain`) whether it is open or the refusal
+     * the cancel would answer, in the cancel's own words. `refusal` is set when the cancel would
+     * be refused whatever is decided. Read now and without a lock: the cancel judges it again.
+     * Needs `UpdateOrder`, as the cancel does. Another store's order is a `NotFoundError`.
+     */
+    previewCancelWithMoney(orderId: string, options?: Call): Promise<OrderCancelMoneyPreview>;
+}
+export declare function createOrderCancelWithMoneyModule(transport: Transport): OrderCancelWithMoneyModule;

package/dist/orders/cancel-with-money.js

@@ -0,0 +1,153 @@
+import { creditNotedAware } from '../payments/credit-noted-fields.js';
+import { STORE_CREDIT_MOVE_FIELDS, storeCreditAware } from '../payments/store-credit-fields.js';
+const OPTION_FIELDS = /* GraphQL */ `
+  available
+  code
+  message
+  book
+`;
+/**
+ * Its own document, like the cancel's: on an engine without the query this call alone fails
+ * validation.
+ */
+export const CANCEL_ORDER_WITH_MONEY_PREVIEW_QUERY = /* GraphQL */ `
+  query CancelOrderWithMoneyPreview($orderId: ID!) {
+    cancelOrderWithMoneyPreview(orderId: $orderId) {
+      orderId
+      currencyCode
+      settledHeld
+      giftCardHeld
+      holds {
+        paymentId
+        method
+        amount
+      }
+      refunds {
+        paymentId
+        method
+        amount
+        payout
+      }
+      refund { ${OPTION_FIELDS} }
+      accountCredit { ${OPTION_FIELDS} }
+      retain { ${OPTION_FIELDS} }
+      refusal {
+        code
+        message
+      }
+      position {
+        total
+        covered
+        settled
+        authorized
+        refunded
+        creditedToAccount
+        creditNoted
+        owed
+        outstanding
+        overpaid
+        availableToCharge
+      }
+    }
+  }
+`;
+/**
+ * Its own document on purpose: `cancelOrderWithMoney` exists only on an engine that serves it,
+ * so on an older one this call alone fails validation and no other order call does.
+ */
+export const CANCEL_ORDER_WITH_MONEY_MUTATION = /* GraphQL */ `
+  mutation CancelOrderWithMoney($input: CancelOrderWithMoneyInput!, $idempotencyKey: String) {
+    cancelOrderWithMoney(input: $input, idempotencyKey: $idempotencyKey) {
+      order {
+        id
+        code
+        state
+        currencyCode
+        total
+        totalWithTax
+      }
+      refunds {
+        id
+        total
+        state
+        method
+        transactionId
+        reason
+      }
+      retained
+      refundPayouts {
+        refundId
+        paymentId
+        payout
+      }
+      creditedToAccount
+      creditedToStoreCredit
+      storeCredit { ${STORE_CREDIT_MOVE_FIELDS} }
+      voidedHolds {
+        paymentId
+        method
+        amount
+      }
+      position {
+        total
+        covered
+        settled
+        authorized
+        refunded
+        creditedToAccount
+        creditNoted
+        owed
+        outstanding
+        overpaid
+        availableToCharge
+      }
+    }
+  }
+`;
+/** An option as the SDK types it: `code` and `message` are null when it is open. */
+function toOption(raw) {
+    return {
+        available: raw.available,
+        code: raw.code ?? null,
+        message: raw.message ?? null,
+        book: raw.book ?? null,
+    };
+}
+export function createOrderCancelWithMoneyModule(transport) {
+    return {
+        async cancelWithMoney(orderId, options) {
+            const data = await storeCreditAware(creditNotedAware(transport)).graphql({
+                api: 'admin',
+                query: CANCEL_ORDER_WITH_MONEY_MUTATION,
+                // `undefined`, never an explicit null: `JSON.stringify` drops it, so an option left out
+                // stays off the wire rather than arriving as a value.
+                variables: {
+                    input: {
+                        orderId,
+                        reason: options?.reason,
+                        overpayment: options?.overpayment,
+                        retain: options?.retain,
+                    },
+                    idempotencyKey: options?.idempotencyKey,
+                },
+            }, options);
+            const outcome = data.cancelOrderWithMoney;
+            return {
+                ...outcome,
+                creditedToStoreCredit: outcome.creditedToStoreCredit ?? 0,
+                storeCredit: outcome.storeCredit ?? null,
+            };
+        },
+        async previewCancelWithMoney(orderId, options) {
+            const data = await storeCreditAware(creditNotedAware(transport)).graphql({ api: 'admin', query: CANCEL_ORDER_WITH_MONEY_PREVIEW_QUERY, variables: { orderId } }, options);
+            const preview = data.cancelOrderWithMoneyPreview;
+            return {
+                ...preview,
+                refund: toOption(preview.refund),
+                accountCredit: toOption(preview.accountCredit),
+                retain: toOption(preview.retain),
+                refusal: preview.refusal ?? null,
+            };
+        },
+    };
+}

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

@@ -1,4 +1,5 @@
 import { type Transport } from '@sixtyninecommerce/core';
+import type { StoreCreditMove } from '../payments/account-credit.js';
 import type { Call } from '../types.js';
 import type { OrderEditDiff, OrderEditPlan } from './plan-edit.js';
 import type { OrderOverpaymentChoice } from './surcharges.js';
@@ -32,6 +33,11 @@ export interface OrderEditOverpaymentSettlement {
     currencyCode: string;
     /** For `ACCOUNT_CREDIT`: the receipts on the customer's account, one per payment it came from. */
     unappliedCashIds: string[];
+    /**
+     * For `ACCOUNT_CREDIT` in a store whose book is store credit: the move to the customer's
+     * wallet (`unappliedCashIds` is then empty). Null otherwise; absent from an engine before it.
+     */
+    storeCredit?: StoreCreditMove | null;
 }
 export interface OrderEditCommit {
     order: OrderEditCommittedOrder;
@@ -71,7 +77,7 @@ export interface CommitOrderEditCall extends Call {
  * Its own document on purpose: `commitOrderEdit` exists only on an engine with the order-edit
  * commit, so on an older one this call alone fails validation and no other order call does.
  */
-export declare const COMMIT_ORDER_EDIT_MUTATION = "\n  mutation CommitOrderEdit(\n    $orderId: ID!\n    $diff: OrderEditDiffInput!\n    $expectedPlanHash: String!\n    $idempotencyKey: String!\n    $overpaymentChoice: OrderOverpaymentChoice\n  ) {\n    commitOrderEdit(\n      orderId: $orderId\n      diff: $diff\n      expectedPlanHash: $expectedPlanHash\n      idempotencyKey: $idempotencyKey\n      overpaymentChoice: $overpaymentChoice\n    ) {\n      order {\n        id\n        code\n        state\n        currencyCode\n        totalWithTax\n      }\n      plan {\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          }\n          accountCredit {\n            available\n            code\n            message\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      refund {\n        id\n        state\n        total\n        paymentId\n      }\n      overpayment {\n        choice\n        amount\n        currencyCode\n        unappliedCashIds\n      }\n    }\n  }\n";
+export declare const COMMIT_ORDER_EDIT_MUTATION = "\n  mutation CommitOrderEdit(\n    $orderId: ID!\n    $diff: OrderEditDiffInput!\n    $expectedPlanHash: String!\n    $idempotencyKey: String!\n    $overpaymentChoice: OrderOverpaymentChoice\n  ) {\n    commitOrderEdit(\n      orderId: $orderId\n      diff: $diff\n      expectedPlanHash: $expectedPlanHash\n      idempotencyKey: $idempotencyKey\n      overpaymentChoice: $overpaymentChoice\n    ) {\n      order {\n        id\n        code\n        state\n        currencyCode\n        totalWithTax\n      }\n      plan {\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      refund {\n        id\n        state\n        total\n        paymentId\n      }\n      overpayment {\n        choice\n        amount\n        currencyCode\n        unappliedCashIds\n        storeCredit { accountId amount currencyCode entryIds }\n      }\n    }\n  }\n";
 export interface OrderCommitEditModule {
     /**
      * Carry out an edit of a placed order as its plan (`planEdit`) states it, once. Needs

package/dist/orders/commit-edit.js

@@ -1,4 +1,5 @@
 import { idempotencyKey as mintIdempotencyKey } from '@sixtyninecommerce/core';
+import { STORE_CREDIT_MOVE_FIELDS, storeCreditAware } from '../payments/store-credit-fields.js';
 /**
  * Its own document on purpose: `commitOrderEdit` exists only on an engine with the order-edit
  * commit, so on an older one this call alone fails validation and no other order call does.
@@ -46,11 +47,13 @@ export const COMMIT_ORDER_EDIT_MUTATION = /* GraphQL */ `
             available
             code
             message
+            book
           }
           accountCredit {
             available
             code
             message
+            book
           }
           refundWhenChosen {
             paymentId
@@ -103,6 +106,7 @@ export const COMMIT_ORDER_EDIT_MUTATION = /* GraphQL */ `
         amount
         currencyCode
         unappliedCashIds
+        storeCredit { ${STORE_CREDIT_MOVE_FIELDS} }
       }
     }
   }
@@ -112,7 +116,7 @@ export function createOrderCommitEditModule(transport) {
         async commitEdit(orderId, diff, options) {
             const key = options.idempotencyKey ?? mintIdempotencyKey();
             try {
-                const data = await transport.graphql({
+                const data = await storeCreditAware(transport).graphql({
                     api: 'admin',
                     query: COMMIT_ORDER_EDIT_MUTATION,
                     // The diff goes out as given, never normalised (see `planEdit`): left out, `null` and