@sixtyninecommerce/admin 0.9.0 → 0.11.0

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

package/dist/orders/deposit-policy.d.ts

@@ -0,0 +1,103 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** The fewest days `autoCancelAfterDays` may be; `null` means never. */
+export declare const DEPOSIT_POLICY_AUTO_CANCEL_DAYS_MIN = 1;
+/** The largest `storefront.minimumPercent`: a whole percentage of the order total. */
+export declare const DEPOSIT_POLICY_MINIMUM_PERCENT_MAX = 100;
+/** The most payment method codes `storefront.methods` may name. */
+export declare const DEPOSIT_POLICY_STOREFRONT_METHODS_MAX = 50;
+/** Deposits a SHOPPER pays online at checkout. Applies only while `enabled` is on as well. */
+export interface StorefrontDepositPolicy {
+    /** The online switch. */
+    enabled: boolean;
+    /**
+     * Payment method CODES a shopper may pay a deposit with: offline methods and
+     * Mollie. Empty: none, so no shopper can pay a deposit online.
+     */
+    methods: string[];
+    /**
+     * The least an online deposit may be, as a whole percentage (0–100) of the
+     * order's total, judged in the order's currency. Beside `minimum`, not instead
+     * of it: the larger of the two applies.
+     */
+    minimumPercent: number;
+}
+/**
+ * The store's deposit policy (`Channel.customFields.orderDepositPolicy`): whether
+ * staff may take a deposit and park an order (`orders.park`), and whether a
+ * shopper may pay one at checkout. Every field present: this is what the engine
+ * APPLIES, absent and malformed fields read as their defaults.
+ */
+export interface OrderDepositPolicy {
+    /**
+     * The store-wide switch. Off: a payment must cover the whole outstanding
+     * amount (`payments.record` refuses a part payment `DEPOSITS_NOT_ENABLED`) and
+     * no order can be parked.
+     */
+    enabled: boolean;
+    /**
+     * The least a deposit must be before an order can be parked, in minor units of
+     * the store's DEFAULT currency; 0 means any deposit will do. An order in another
+     * currency is held to it converted at the rate checkout charges with.
+     */
+    minimum: number;
+    /** Whether an order may be parked with nothing paid at all. */
+    allowZeroDepositPark: boolean;
+    /**
+     * Whether the storefront shows a parked order's reason to the shopper. Off by
+     * default: staff write that reason for staff.
+     */
+    showParkReasonToCustomer: boolean;
+    /**
+     * RESERVED: days after which a parked order is cancelled. Saved and read back,
+     * but nothing cancels a parked order automatically yet. `null`: never.
+     */
+    autoCancelAfterDays: number | null;
+    storefront: StorefrontDepositPolicy;
+}
+/**
+ * The policy of a store that never set one, and of every field that cannot be
+ * read: deposits off, no minimum, no zero-deposit park, the reason kept from the
+ * shopper, never auto-cancelled, no online deposits.
+ */
+export declare const DEFAULT_ORDER_DEPOSIT_POLICY: Readonly<OrderDepositPolicy>;
+/**
+ * The ACTIVE store's deposit policy (`admin.orders.depositPolicy`), stored as a
+ * Channel custom field and written through core `updateChannel`.
+ *
+ * Reading needs an authenticated administrator on the store; writing needs
+ * `UpdateChannel`.
+ */
+export interface OrderDepositPolicyModule {
+    /**
+     * The policy the engine applies, read as tolerantly as the engine reads it: a
+     * store that never set one, a malformed column and a field of the wrong type
+     * all answer their defaults ({@link DEFAULT_ORDER_DEPOSIT_POLICY}), so this is
+     * what `orders.park` and `payments.record` will hold an order to.
+     */
+    get(options?: Call): Promise<OrderDepositPolicy>;
+    /**
+     * Replace the whole policy, and answer it as the engine now applies it.
+     *
+     * Every field is required: read it with {@link get}, change what you mean to,
+     * and send it back. Only the schema's fields are stored (anything else on the
+     * object is left out), and the method codes are stored as given.
+     *
+     * Refused before any request with `DEPOSIT_POLICY_INVALID` ({@link ValidationError},
+     * one `details[]` entry per failing field, named by its path such as
+     * `storefront.minimumPercent`): a non-boolean switch, a `minimum` that is not a
+     * whole number of 0 or more, an `autoCancelAfterDays` that is neither `null` nor
+     * a whole number of 1 or more, a `minimumPercent` outside 0–100, a blank or
+     * repeated method code, or more than 50 of them. The engine itself stores any
+     * JSON in the column and reads what it cannot use as the default, so this check
+     * is what keeps a bad value from silently turning deposits off.
+     *
+     * Absent and "set to the defaults" mean the same thing to the engine, and a
+     * store's column is never backfilled: write the policy when a merchant changed
+     * it, not as a side effect of saving something else.
+     */
+    set(policy: OrderDepositPolicy, options?: Call): Promise<OrderDepositPolicy>;
+}
+export declare const ORDER_DEPOSIT_POLICY_QUERY = "\n  query OrderDepositPolicy {\n    activeChannel { \n  id\n  customFields {\n    orderDepositPolicy\n  }\n }\n  }\n";
+export declare const SET_ORDER_DEPOSIT_POLICY_MUTATION = "\n  mutation SetOrderDepositPolicy($input: UpdateChannelInput!) {\n    updateChannel(input: $input) {\n      ... on Channel { \n  id\n  customFields {\n    orderDepositPolicy\n  }\n }\n      ... on ErrorResult { errorCode message }\n    }\n  }\n";
+export declare function createOrderDepositPolicyModule(transport: Transport): OrderDepositPolicyModule;