@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/orders/status.d.ts

@@ -0,0 +1,235 @@
+/**
+ * `admin.orders.status(orderId)`: why an order is the way it is, and what can
+ * be done to it (headless spec §7 `orders.status`, plan W9-8).
+ *
+ * One derived read, so a head does not re-derive the lock, the edit block,
+ * the allocation badge or the status menu from the order's fields. It is the
+ * engine's root `orderStatus` query, never a field on an order list.
+ *
+ * The four lists below are the engine's own, pinned to it by
+ * `__tests__/orders-status.spec.ts`. The engine adds to them over time, so
+ * every field that carries one also accepts a string this version does not
+ * name: treat an unknown value as "not available".
+ */
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** Which of the lock's two writers locked the order. */
+export declare const ORDER_LOCK_REASONS: readonly ["NONE", "INVOICE", "IMPORTED", "UNKNOWN"];
+/**
+ * `NONE`: not locked. `INVOICE`: an invoice was issued for it on this
+ * platform. `IMPORTED`: the source platform had already invoiced it, and this
+ * platform holds no invoice for it. `UNKNOWN`: locked, cause not established.
+ */
+export type OrderLockReason = (typeof ORDER_LOCK_REASONS)[number];
+/** What to show for the order's stock-reservation expiry. */
+export declare const ORDER_ALLOCATION_BADGES: readonly ["HIDDEN", "RESERVED", "EXPIRED"];
+/**
+ * `EXPIRED` means the allocation sweeper WILL cancel the order. An order it
+ * leaves alone (placed, holding money, parked, held by a fulfillment) is never
+ * `EXPIRED`. `RESERVED`: the expiry is ahead, or the order is parked and keeps
+ * its stock. `HIDDEN`: no expiry applies.
+ */
+export type OrderAllocationBadge = (typeof ORDER_ALLOCATION_BADGES)[number];
+/** Why an order's content may not change. */
+export declare const ORDER_EDIT_BLOCK_CODES: readonly ["INVOICE_LOCKED", "COMPLETED", "CANCELLED"];
+export type OrderEditBlockCode = (typeof ORDER_EDIT_BLOCK_CODES)[number];
+/** The actions the engine answers for, in the order it lists them. */
+export declare const ORDER_STATUS_ACTIONS: readonly ["MODIFY", "DELETE", "RELEASE_ALLOCATION", "CORRECT_FULFILLMENT", "CANCEL", "TRANSITION", "MARK_COMPLETED", "REOPEN"];
+/**
+ * One thing that can be done to an order, with the engine write behind it and
+ * what `allowed` asks of the caller:
+ *
+ * - `MODIFY`: the Edit Order flow, whose write is `modifyOrder`. That write
+ *   runs only while the order is in the `Modifying` state, so the flow first
+ *   moves the order there (`transitionOrderToState`; `Modifying` is never in
+ *   `nextStates`), calls `modifyOrder`, and moves the order out again.
+ *   `eligible` says the flow can OPEN from the order's present state, so an
+ *   order already in `Modifying` answers `STATE`. Needs `UpdateOrder`.
+ * - `DELETE`: `deleteOrder`. Needs `DeleteOrder`. The write refuses what this
+ *   action reports: an invoiced order (`INVOICE_LOCKED` here,
+ *   `ORDER_INVOICE_LOCKED` from the write, for every caller) and an order a
+ *   payment or a stock movement is recorded on (`HAS_RECORDS` here,
+ *   `ORDER_HAS_RECORDS` from the write).
+ * - `RELEASE_ALLOCATION`: `releaseOrderAllocation`. Needs `UpdateOrder`. The
+ *   write refuses an invoiced order for every caller (`INVOICE_LOCKED` here,
+ *   `ORDER_INVOICE_LOCKED` from the write). A credential restricted to stock
+ *   locations (an API token or app installation with `locationIds`) must also
+ *   hold every location the order's reservation sits at; otherwise the release
+ *   answers `LOCATION_NOT_ALLOWED` and this action `PERMISSION`.
+ * - `CANCEL`: `cancelOrder` for the whole order. Needs `UpdateOrder`.
+ * - `TRANSITION`: `transitionOrderToState` into one of `nextStates`. Needs
+ *   `UpdateOrder`.
+ * - `MARK_COMPLETED`: `markOrderCompleted`. Needs `UpdateOrder`.
+ * - `REOPEN`: `reopenOrder`. Needs `UpdateOrder`.
+ * - `CORRECT_FULFILLMENT`: one of TWO writes, with different gates.
+ *   - `updateFulfillmentLineQuantities` needs `UpdateOrder`, and corrects any
+ *     fulfillment of the order on any store.
+ *   - `correctFulfillmentQuantities` needs `UpdateFulfillment` or
+ *     `UpdateOrder`, and works only on a store with the warehouse workspace
+ *     (`WAREHOUSE_NOT_ENABLED` otherwise). For a caller without `UpdateOrder`
+ *     it corrects only a fulfillment that ships from a warehouse the caller is
+ *     assigned to (any other answers `LOCATION_OUT_OF_SCOPE`, a fulfillment
+ *     with no recorded warehouse included), and it cannot lower the ordered
+ *     quantity (`OFFICE_ONLY`).
+ *
+ *   So `allowed` is true for a caller with `UpdateOrder` whenever the order is
+ *   eligible. For a caller holding `UpdateFulfillment` without `UpdateOrder`
+ *   it is true only on a store with the warehouse workspace, and only while
+ *   at least one of THIS order's fulfillments ships from one of the caller's
+ *   warehouses. That caller must call `correctFulfillmentQuantities`: the
+ *   other write answers `FORBIDDEN`. An order with no fulfillment gives such a
+ *   caller `PERMISSION`.
+ *
+ *   It is an order-level answer. Whether a given fulfillment can still be
+ *   corrected (Pending or Picking, or Packed with no carrier booking) is that
+ *   fulfillment's own state, and is not answered here.
+ */
+export type OrderStatusActionName = (typeof ORDER_STATUS_ACTIONS)[number];
+/** Why an action is not allowed, in the order the engine lists them. */
+export declare const ORDER_STATUS_REASON_CODES: readonly ["INVOICE_LOCKED", "COMPLETED", "CANCELLED", "STATE", "NOTHING_ALLOCATED", "HAS_RECORDS", "NOTHING_TO_CANCEL", "SHOPPER_CART", "UNITS_SHIPPED", "ACTIVE_FULFILLMENT", "PERMISSION"];
+/**
+ * - `INVOICE_LOCKED`, `COMPLETED`, `CANCELLED`: the edit block.
+ * - `STATE`: the order's state does not allow it.
+ * - `NOTHING_ALLOCATED`: no line holds stock to release.
+ * - `HAS_RECORDS`: the order carries a payment or a stock movement, which a
+ *   delete cannot remove. A draft, or a shopper's live cart, is cancelled
+ *   instead: `CANCEL` is open on it.
+ * - `NOTHING_TO_CANCEL`: the order's lines hold no unit. Delete an empty
+ *   draft instead.
+ * - `SHOPPER_CART`: a live cart, a shopper's or a till's open sale in the cart
+ *   state. Its status is not moved, completed or reopened. `CANCEL` answers it
+ *   too on a cart with no payment and no stock movement (delete it instead)
+ *   and on a till's open sale (ended at the till).
+ * - `UNITS_SHIPPED`: a shipped or delivered fulfillment holds a line. Those
+ *   units come back through a return.
+ * - `ACTIVE_FULFILLMENT`: a fulfillment not yet shipped holds a line. Detach
+ *   the order from it or correct its quantities first.
+ * - `PERMISSION`: the order allows it and this caller may not. The only
+ *   reason about the caller.
+ */
+export type OrderStatusReasonCode = (typeof ORDER_STATUS_REASON_CODES)[number];
+/** One thing that can be done to the order: see {@link OrderStatusActionName}. */
+export interface OrderStatusAction {
+    action: OrderStatusActionName | (string & {});
+    /** The ORDER allows it, whoever asks. */
+    eligible: boolean;
+    /** This caller may do it now: eligible, and the caller may take a write that does it. */
+    allowed: boolean;
+    /** Null exactly when `allowed`. Otherwise why not: see {@link OrderStatusReasonCode}. */
+    reasonCode: OrderStatusReasonCode | (string & {}) | null;
+}
+/** An app provider the order runs without (see `admin.orders.providerFallbacks`). */
+export interface OrderStatusProviderFallback {
+    /** `shipping.rates`, `tax.calculate`, and others over time. */
+    kind: string;
+    installationId: string;
+    reason: string;
+    /** ISO-8601 with offset. */
+    since: string;
+}
+export interface OrderStatusView {
+    orderId: string;
+    /** The engine state. */
+    state: string;
+    /**
+     * The four projected dimensions. `status` is `draft`, `open`, `completed` or
+     * `cancelled`. Each is null on an order that predates them, and for a moment
+     * on an order just created or changed: the engine writes them after the
+     * change that causes them.
+     */
+    lifecycle: {
+        status: string | null;
+        payment: string | null;
+        fulfillment: string | null;
+        return: string | null;
+    };
+    lock: {
+        locked: boolean;
+        reason: OrderLockReason | (string & {});
+        /**
+         * Set only when the reason is `INVOICE`: the live standard invoice, else a
+         * voided standard one (voiding does not unlock the order).
+         */
+        lockingInvoice: {
+            id: string;
+            number: string;
+            voided: boolean;
+        } | null;
+    };
+    /** Null when the order's content may change; the message is the one every edit is refused with. */
+    editBlock: {
+        code: OrderEditBlockCode | (string & {});
+        message: string;
+    } | null;
+    /** The Edit Order flow opens for this order. It may still be refused by `editBlock`. */
+    modifiable: boolean;
+    /** A deletable state on an order no invoice locks, carrying no payment and no stock movement. */
+    deletable: boolean;
+    /**
+     * The units `releaseOrderAllocation` would free now: the sum of the net
+     * reservations of the lines that still hold stock. Never negative. A line
+     * whose ledger nets below zero releases nothing and cancels nothing out, so
+     * this can be above zero while the lines' total is not.
+     */
+    releasableUnits: number;
+    /**
+     * A releasable state, no invoice lock, and `releasableUnits` above zero.
+     * The order's answer: the `RELEASE_ALLOCATION` action adds whether this
+     * caller may.
+     */
+    releaseAllowed: boolean;
+    allocationBadge: OrderAllocationBadge | (string & {});
+    /**
+     * The edit block on correcting a fulfillment's quantities. The
+     * `CORRECT_FULFILLMENT` action adds whether this caller may.
+     */
+    fulfillmentCorrection: {
+        blocked: boolean;
+        code: OrderEditBlockCode | (string & {}) | null;
+    };
+    /**
+     * The source platform already handed this imported order to its own
+     * fulfillment provider, and the store blocks shipping it again.
+     */
+    sourceFulfilled: boolean;
+    /** Set while the order is parked. */
+    park: {
+        reason: string | null;
+    } | null;
+    /**
+     * Set while a paid order is held for review: the code of the first refusal
+     * the order met after the buyer paid, and the slug of the app that refused
+     * it when an app did.
+     */
+    hold: {
+        forReview: string | null;
+        byApp: string | null;
+    } | null;
+    /** Empty when the order runs on every provider the store assigned. */
+    providerFallbacks: OrderStatusProviderFallback[];
+    /**
+     * The states a change-status menu lists, in the engine's order: without
+     * `Cancelled` and `Modifying` (their own actions), without the cart phase,
+     * and without the fulfillment states while the order has no fulfillment.
+     * Empty on a live cart.
+     */
+    nextStates: string[];
+    actions: OrderStatusAction[];
+}
+export declare const ORDER_STATUS_QUERY = "\n  query OrderStatus($orderId: ID!) {\n    orderStatus(orderId: $orderId) {\n      orderId\n      state\n      lifecycle {\n        status\n        payment\n        fulfillment\n        return\n      }\n      lock {\n        locked\n        reason\n        lockingInvoice {\n          id\n          number\n          voided\n        }\n      }\n      editBlock {\n        code\n        message\n      }\n      modifiable\n      deletable\n      releasableUnits\n      releaseAllowed\n      allocationBadge\n      fulfillmentCorrection {\n        blocked\n        code\n      }\n      sourceFulfilled\n      park {\n        reason\n      }\n      hold {\n        forReview\n        byApp\n      }\n      providerFallbacks {\n        kind\n        installationId\n        reason\n        since\n      }\n      nextStates\n      actions {\n        action\n        eligible\n        allowed\n        reasonCode\n      }\n    }\n  }\n";
+export interface OrderStatusModule {
+    /**
+     * Why the order is the way it is, and the actions open to this caller.
+     * Needs `ReadOrder`.
+     *
+     * An order this store does not hold is a `NotFoundError`
+     * (`ENTITY_NOT_FOUND`), the same as a missing id. Each action says whether
+     * the ORDER allows it (`eligible`) and whether THIS caller may take it now
+     * (`allowed`), so a head can show an action greyed out with its reason.
+     *
+     * Needs an engine that serves `orderStatus`; against an older one this call
+     * fails validation and nothing else does.
+     */
+    status(orderId: string, options?: Call): Promise<OrderStatusView>;
+}
+export declare function createOrderStatusModule(transport: Transport): OrderStatusModule;

package/dist/orders/status.js

@@ -0,0 +1,96 @@
+/** Which of the lock's two writers locked the order. */
+export const ORDER_LOCK_REASONS = ['NONE', 'INVOICE', 'IMPORTED', 'UNKNOWN'];
+/** What to show for the order's stock-reservation expiry. */
+export const ORDER_ALLOCATION_BADGES = ['HIDDEN', 'RESERVED', 'EXPIRED'];
+/** Why an order's content may not change. */
+export const ORDER_EDIT_BLOCK_CODES = ['INVOICE_LOCKED', 'COMPLETED', 'CANCELLED'];
+/** The actions the engine answers for, in the order it lists them. */
+export const ORDER_STATUS_ACTIONS = [
+    'MODIFY',
+    'DELETE',
+    'RELEASE_ALLOCATION',
+    'CORRECT_FULFILLMENT',
+    'CANCEL',
+    'TRANSITION',
+    'MARK_COMPLETED',
+    'REOPEN',
+];
+/** Why an action is not allowed, in the order the engine lists them. */
+export const ORDER_STATUS_REASON_CODES = [
+    'INVOICE_LOCKED',
+    'COMPLETED',
+    'CANCELLED',
+    'STATE',
+    'NOTHING_ALLOCATED',
+    'HAS_RECORDS',
+    'NOTHING_TO_CANCEL',
+    'SHOPPER_CART',
+    'UNITS_SHIPPED',
+    'ACTIVE_FULFILLMENT',
+    'PERMISSION',
+];
+export const ORDER_STATUS_QUERY = /* GraphQL */ `
+  query OrderStatus($orderId: ID!) {
+    orderStatus(orderId: $orderId) {
+      orderId
+      state
+      lifecycle {
+        status
+        payment
+        fulfillment
+        return
+      }
+      lock {
+        locked
+        reason
+        lockingInvoice {
+          id
+          number
+          voided
+        }
+      }
+      editBlock {
+        code
+        message
+      }
+      modifiable
+      deletable
+      releasableUnits
+      releaseAllowed
+      allocationBadge
+      fulfillmentCorrection {
+        blocked
+        code
+      }
+      sourceFulfilled
+      park {
+        reason
+      }
+      hold {
+        forReview
+        byApp
+      }
+      providerFallbacks {
+        kind
+        installationId
+        reason
+        since
+      }
+      nextStates
+      actions {
+        action
+        eligible
+        allowed
+        reasonCode
+      }
+    }
+  }
+`;
+export function createOrderStatusModule(transport) {
+    return {
+        async status(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: ORDER_STATUS_QUERY, variables: { orderId } }, options);
+            return data.orderStatus;
+        },
+    };
+}

package/dist/orders/surcharges.d.ts

@@ -29,8 +29,33 @@ export interface SurchargeInput {
      */
     taxDescription?: string | null;
 }
+/**
+ * How money a change owes a PAID order's customer back is settled: `REFUND`
+ * to their payment, or `ACCOUNT_CREDIT` to their account as unapplied cash
+ * (`payments.accountCredit`).
+ */
+export type OrderOverpaymentChoice = 'REFUND' | 'ACCOUNT_CREDIT';
+/** Options for a surcharge removal. */
+export interface SurchargeRemoveCall extends Call {
+    /**
+     * On an order the customer has PAID, how the money a lowered or removed
+     * charge owes them back is settled. Without it such a change is refused
+     * `ORDER_EDIT_OVERPAYMENT_CHOICE_REQUIRED` (→ `BusinessRuleError`), nothing
+     * written: ask the merchant (`preview` names the amount and which options
+     * are open), then send it again. Ignored when nothing is owed back.
+     *
+     * `REFUND` is refused `REFUND_EXCEEDS_PAYMENT` when no single payment can
+     * carry the amount, `ORDER_OVERPAYMENT_REFUND_ORDER_STATE` on an order
+     * in a state core does not refund, and `REFUND_METHOD_UNAVAILABLE`
+     * when that payment's method can no longer be reached; `ACCOUNT_CREDIT` by the account's own refusal
+     * (`AR_ACCOUNT_REQUIRED`, `AR_ACCOUNT_IN_ERP`, `AR_ORDER_ALREADY_INVOICED`,
+     * `AR_LEDGER_NOT_ENABLED`). A refund of unknown outcome on the order refuses
+     * either (`ORDER_OVERPAYMENT_REFUND_UNRECONCILED`) until it is reconciled.
+     */
+    overpayment?: OrderOverpaymentChoice;
+}
 /** Options for a surcharge write. */
-export interface SurchargeCall extends Call {
+export interface SurchargeCall extends SurchargeRemoveCall {
     /**
      * Price the surcharge from one of the store's tax classes (spec §8.6)
      * instead of from an explicit `taxRate`.
@@ -89,6 +114,43 @@ export interface SurchargedOrder {
         taxRate: number;
     }>;
 }
+/** One surcharge change to preview: an add, an update, or a removal. */
+export type SurchargeChange = {
+    input: SurchargeInput;
+    surchargeId?: never;
+    remove?: never;
+} | {
+    surchargeId: string;
+    input: SurchargeInput;
+    remove?: never;
+} | {
+    surchargeId: string;
+    remove: true;
+    input?: never;
+};
+/** Whether one way of settling an overpayment is open; when not, the refusal it would answer. */
+export interface OverpaymentOption {
+    available: boolean;
+    code: string | null;
+    message: string | null;
+}
+/** What a surcharge change would do to an order's money. Nothing was saved. */
+export interface SurchargeChangePreview {
+    currencyCode: string;
+    /** The order's billable total with tax, minor units, before and after the change. */
+    totalBefore: number;
+    totalAfter: number;
+    /**
+     * On a paid order: what the change would owe the customer back, and the
+     * ways to settle it. Null when it owes nothing.
+     */
+    overpayment: {
+        amount: number;
+        currencyCode: string;
+        refund: OverpaymentOption;
+        accountCredit: OverpaymentOption;
+    } | null;
+}
 /**
  * Surcharges on a placed order.
  *
@@ -113,9 +175,20 @@ export interface SurchargesModule {
      */
     update(orderId: string, surchargeId: string, input: SurchargeInput, options?: SurchargeCall): Promise<SurchargedOrder>;
     /** Remove a surcharge entirely and re-total the order. */
-    remove(orderId: string, surchargeId: string, options?: Call): Promise<SurchargedOrder>;
+    remove(orderId: string, surchargeId: string, options?: SurchargeRemoveCall): Promise<SurchargedOrder>;
+    /**
+     * What one change would do, before it is saved: run in a transaction the
+     * engine always rolls back, so nothing is written or announced. On a paid
+     * order it names what the customer would be owed back and which choices are
+     * open. Needs `UpdateOrder`, as the change itself does.
+     */
+    preview(orderId: string, change: SurchargeChange, options?: Pick<SurchargeCall, 'taxClass'> & Call): Promise<SurchargeChangePreview>;
 }
 export declare const ADD_ORDER_SURCHARGE_MUTATION = "\n  mutation AddOrderSurcharge(\n    $orderId: ID!\n    $input: SurchargeInput!\n    $taxClass: String\n    $idempotencyKey: String\n  ) {\n    addOrderSurcharge(\n      orderId: $orderId\n      input: $input\n      taxClass: $taxClass\n      idempotencyKey: $idempotencyKey\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
+export declare const ADD_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION = "\n  mutation AddOrderSurchargeWithOverpayment(\n    $orderId: ID!\n    $input: SurchargeInput!\n    $taxClass: String\n    $idempotencyKey: String\n    $overpayment: OrderOverpaymentChoice\n  ) {\n    addOrderSurcharge(\n      orderId: $orderId\n      input: $input\n      taxClass: $taxClass\n      idempotencyKey: $idempotencyKey\n      overpayment: $overpayment\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
 export declare const UPDATE_ORDER_SURCHARGE_MUTATION = "\n  mutation UpdateOrderSurcharge(\n    $orderId: ID!\n    $surchargeId: ID!\n    $input: SurchargeInput!\n    $taxClass: String\n    $idempotencyKey: String\n  ) {\n    updateOrderSurcharge(\n      orderId: $orderId\n      surchargeId: $surchargeId\n      input: $input\n      taxClass: $taxClass\n      idempotencyKey: $idempotencyKey\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
+export declare const UPDATE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION = "\n  mutation UpdateOrderSurchargeWithOverpayment(\n    $orderId: ID!\n    $surchargeId: ID!\n    $input: SurchargeInput!\n    $taxClass: String\n    $idempotencyKey: String\n    $overpayment: OrderOverpaymentChoice\n  ) {\n    updateOrderSurcharge(\n      orderId: $orderId\n      surchargeId: $surchargeId\n      input: $input\n      taxClass: $taxClass\n      idempotencyKey: $idempotencyKey\n      overpayment: $overpayment\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
 export declare const REMOVE_ORDER_SURCHARGE_MUTATION = "\n  mutation RemoveOrderSurcharge($orderId: ID!, $surchargeId: ID!, $idempotencyKey: String) {\n    removeOrderSurcharge(\n      orderId: $orderId\n      surchargeId: $surchargeId\n      idempotencyKey: $idempotencyKey\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
+export declare const REMOVE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION = "\n  mutation RemoveOrderSurchargeWithOverpayment(\n    $orderId: ID!\n    $surchargeId: ID!\n    $idempotencyKey: String\n    $overpayment: OrderOverpaymentChoice\n  ) {\n    removeOrderSurcharge(\n      orderId: $orderId\n      surchargeId: $surchargeId\n      idempotencyKey: $idempotencyKey\n      overpayment: $overpayment\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
+export declare const PREVIEW_ORDER_SURCHARGE_CHANGE_QUERY = "\n  query PreviewOrderSurchargeChange($orderId: ID!, $change: OrderSurchargeChangeInput!) {\n    previewOrderSurchargeChange(orderId: $orderId, change: $change) {\n      currencyCode\n      totalBefore\n      totalAfter\n      overpayment {\n        amount\n        currencyCode\n        refund { available code message }\n        accountCredit { available code message }\n      }\n    }\n  }\n";
 export declare function createSurchargesModule(transport: Transport): SurchargesModule;

package/dist/orders/surcharges.js

@@ -13,6 +13,9 @@ const SURCHARGED_ORDER_FIELDS = /* GraphQL */ `
     taxRate
   }
 `;
+// Each write has two documents: without `overpayment` (as it always was), and with it. The
+// variable is declared, and the argument named, only on a call that sends a choice, so an older
+// engine without the argument still accepts every call that does not use it.
 export const ADD_ORDER_SURCHARGE_MUTATION = /* GraphQL */ `
   mutation AddOrderSurcharge(
     $orderId: ID!
@@ -30,6 +33,25 @@ export const ADD_ORDER_SURCHARGE_MUTATION = /* GraphQL */ `
     }
   }
 `;
+export const ADD_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION = /* GraphQL */ `
+  mutation AddOrderSurchargeWithOverpayment(
+    $orderId: ID!
+    $input: SurchargeInput!
+    $taxClass: String
+    $idempotencyKey: String
+    $overpayment: OrderOverpaymentChoice
+  ) {
+    addOrderSurcharge(
+      orderId: $orderId
+      input: $input
+      taxClass: $taxClass
+      idempotencyKey: $idempotencyKey
+      overpayment: $overpayment
+    ) {
+      ${SURCHARGED_ORDER_FIELDS}
+    }
+  }
+`;
 export const UPDATE_ORDER_SURCHARGE_MUTATION = /* GraphQL */ `
   mutation UpdateOrderSurcharge(
     $orderId: ID!
@@ -49,6 +71,27 @@ export const UPDATE_ORDER_SURCHARGE_MUTATION = /* GraphQL */ `
     }
   }
 `;
+export const UPDATE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION = /* GraphQL */ `
+  mutation UpdateOrderSurchargeWithOverpayment(
+    $orderId: ID!
+    $surchargeId: ID!
+    $input: SurchargeInput!
+    $taxClass: String
+    $idempotencyKey: String
+    $overpayment: OrderOverpaymentChoice
+  ) {
+    updateOrderSurcharge(
+      orderId: $orderId
+      surchargeId: $surchargeId
+      input: $input
+      taxClass: $taxClass
+      idempotencyKey: $idempotencyKey
+      overpayment: $overpayment
+    ) {
+      ${SURCHARGED_ORDER_FIELDS}
+    }
+  }
+`;
 export const REMOVE_ORDER_SURCHARGE_MUTATION = /* GraphQL */ `
   mutation RemoveOrderSurcharge($orderId: ID!, $surchargeId: ID!, $idempotencyKey: String) {
     removeOrderSurcharge(
@@ -60,6 +103,44 @@ export const REMOVE_ORDER_SURCHARGE_MUTATION = /* GraphQL */ `
     }
   }
 `;
+export const REMOVE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION = /* GraphQL */ `
+  mutation RemoveOrderSurchargeWithOverpayment(
+    $orderId: ID!
+    $surchargeId: ID!
+    $idempotencyKey: String
+    $overpayment: OrderOverpaymentChoice
+  ) {
+    removeOrderSurcharge(
+      orderId: $orderId
+      surchargeId: $surchargeId
+      idempotencyKey: $idempotencyKey
+      overpayment: $overpayment
+    ) {
+      ${SURCHARGED_ORDER_FIELDS}
+    }
+  }
+`;
+const OVERPAYMENT_OPTION_FIELDS = 'available code message';
+export const PREVIEW_ORDER_SURCHARGE_CHANGE_QUERY = /* GraphQL */ `
+  query PreviewOrderSurchargeChange($orderId: ID!, $change: OrderSurchargeChangeInput!) {
+    previewOrderSurchargeChange(orderId: $orderId, change: $change) {
+      currencyCode
+      totalBefore
+      totalAfter
+      overpayment {
+        amount
+        currencyCode
+        refund { ${OVERPAYMENT_OPTION_FIELDS} }
+        accountCredit { ${OVERPAYMENT_OPTION_FIELDS} }
+      }
+    }
+  }
+`;
+/** The choice as a variable, or `undefined` so it never reaches the wire as null. */
+function overpaymentVariable(options) {
+    const value = options?.overpayment;
+    return value === 'REFUND' || value === 'ACCOUNT_CREDIT' ? value : undefined;
+}
 /**
  * `undefined` rather than `null` for an absent tax class: a variable explicitly
  * set to null is still a value the engine reads, and this argument's whole
@@ -74,12 +155,15 @@ export function createSurchargesModule(transport) {
         async add(orderId, input, options) {
             const data = await transport.graphql({
                 api: 'admin',
-                query: ADD_ORDER_SURCHARGE_MUTATION,
+                query: overpaymentVariable(options) === undefined
+                    ? ADD_ORDER_SURCHARGE_MUTATION
+                    : ADD_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION,
                 variables: {
                     orderId,
                     input,
                     taxClass: taxClassVariable(options),
                     idempotencyKey: options?.idempotencyKey,
+                    overpayment: overpaymentVariable(options),
                 },
             }, options);
             return data.addOrderSurcharge;
@@ -87,13 +171,16 @@ export function createSurchargesModule(transport) {
         async update(orderId, surchargeId, input, options) {
             const data = await transport.graphql({
                 api: 'admin',
-                query: UPDATE_ORDER_SURCHARGE_MUTATION,
+                query: overpaymentVariable(options) === undefined
+                    ? UPDATE_ORDER_SURCHARGE_MUTATION
+                    : UPDATE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION,
                 variables: {
                     orderId,
                     surchargeId,
                     input,
                     taxClass: taxClassVariable(options),
                     idempotencyKey: options?.idempotencyKey,
+                    overpayment: overpaymentVariable(options),
                 },
             }, options);
             return data.updateOrderSurcharge;
@@ -101,10 +188,29 @@ export function createSurchargesModule(transport) {
         async remove(orderId, surchargeId, options) {
             const data = await transport.graphql({
                 api: 'admin',
-                query: REMOVE_ORDER_SURCHARGE_MUTATION,
-                variables: { orderId, surchargeId, idempotencyKey: options?.idempotencyKey },
+                query: overpaymentVariable(options) === undefined
+                    ? REMOVE_ORDER_SURCHARGE_MUTATION
+                    : REMOVE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION,
+                variables: {
+                    orderId,
+                    surchargeId,
+                    idempotencyKey: options?.idempotencyKey,
+                    overpayment: overpaymentVariable(options),
+                },
             }, options);
             return data.removeOrderSurcharge;
         },
+        async preview(orderId, change, options) {
+            const taxClass = taxClassVariable(options);
+            const data = await transport.graphql({
+                api: 'admin',
+                query: PREVIEW_ORDER_SURCHARGE_CHANGE_QUERY,
+                variables: {
+                    orderId,
+                    change: taxClass === undefined ? change : { ...change, taxClass },
+                },
+            }, options);
+            return data.previewOrderSurchargeChange;
+        },
     };
 }