@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/meta/index.d.ts

@@ -39,6 +39,16 @@ 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 return of goods to a supplier's status (`admin.purchasing.returns`). Served by a platform
+     * with supplier returns; absent before.
+     */
+    supplierReturnStatus?: LabelMap;
     /**
      * A vocabulary added after this SDK release arrives camelised, with its map
      * untouched.
@@ -54,6 +64,17 @@ 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;
+    /**
+     * A return of goods to a supplier's lifecycle (`admin.purchasing.returns`): `draft → shipped →
+     * resolved`, and `draft → cancelled`. Served by a platform with supplier returns; absent before.
+     */
+    supplierReturn?: TransitionMap;
     [extra: string]: unknown;
 }
 export interface PermissionGroup {
@@ -108,6 +129,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 +144,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 +301,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/metafields/index.d.ts

@@ -8,8 +8,15 @@ import type { Call } from '../types.js';
  * fields, and commerce refuses a value written against it
  * (`METAFIELD_OWNER_INVALID`). A manifest declaring one still registers; only
  * the value surface says no.
+ *
+ * `purchase_order`, `purchase_order_line` and `supplier` are the purchasing
+ * records, which belong to the store's legal entity rather than to the store:
+ * one of another legal entity answers `NotFoundError` like an id of nothing,
+ * and a store that does not purchase answers `PURCHASING_NOT_ENABLED`. Their
+ * values are still the store's own. An engine older than them refuses them with
+ * `METAFIELD_OWNER_INVALID`.
  */
-export declare const METAFIELD_OWNER_TYPES: readonly ["product", "variant", "customer", "order", "order_line", "location", "collection"];
+export declare const METAFIELD_OWNER_TYPES: readonly ["product", "variant", "customer", "order", "order_line", "location", "collection", "purchase_order", "purchase_order_line", "supplier"];
 export type MetafieldOwnerType = (typeof METAFIELD_OWNER_TYPES)[number];
 /** Scalar value types. `list<T>` of any of them is also a type. */
 export declare const METAFIELD_SCALAR_TYPES: readonly ["text", "number", "money", "boolean", "date", "json", "reference", "attachment"];

package/dist/metafields/index.js

@@ -7,6 +7,13 @@ import { createPage } from '@sixtyninecommerce/core';
  * fields, and commerce refuses a value written against it
  * (`METAFIELD_OWNER_INVALID`). A manifest declaring one still registers; only
  * the value surface says no.
+ *
+ * `purchase_order`, `purchase_order_line` and `supplier` are the purchasing
+ * records, which belong to the store's legal entity rather than to the store:
+ * one of another legal entity answers `NotFoundError` like an id of nothing,
+ * and a store that does not purchase answers `PURCHASING_NOT_ENABLED`. Their
+ * values are still the store's own. An engine older than them refuses them with
+ * `METAFIELD_OWNER_INVALID`.
  */
 export const METAFIELD_OWNER_TYPES = [
     'product',
@@ -16,6 +23,9 @@ export const METAFIELD_OWNER_TYPES = [
     'order_line',
     'location',
     'collection',
+    'purchase_order',
+    'purchase_order_line',
+    'supplier',
 ];
 /** Scalar value types. `list<T>` of any of them is also a type. */
 export const METAFIELD_SCALAR_TYPES = [

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

@@ -0,0 +1,237 @@
+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;
+    /**
+     * With `overpayment: 'ACCOUNT_CREDIT'` in a store whose book is store credit (the 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. Part of the request: a repeat under the same key sends
+     * the same answer. Sent only when given; an engine before the field (incentives sprint 8 PR 6a)
+     * refuses a call that gives it.
+     */
+    customerAgreed?: 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,155 @@
+import { creditNotedAware } from '../payments/credit-noted-fields.js';
+import { customerAgreedVariable } from '../payments/customer-consent.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,
+                        customerAgreed: customerAgreedVariable(options?.customerAgreed),
+                    },
+                    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,
+            };
+        },
+    };
+}