@sixtyninecommerce/admin 0.9.0 → 0.11.0

package/dist/orders/index.d.ts

@@ -1,19 +1,39 @@
 import { type Transport } from '@sixtyninecommerce/core';
+import type { JobHandle } from '../jobs/index.js';
 import type { OrderPaymentPosition, PaidOrder } from '../payments/index.js';
 import type { Call } from '../types.js';
+import { type OrderBulkInput, type OrderBulkRun } from './bulk.js';
+import { type OrderCancelWithMoneyModule } from './cancel-with-money.js';
 import { type OrderCommitEditModule } from './commit-edit.js';
+import { type OrderDepositPolicyModule } from './deposit-policy.js';
+import { type OrderDraftsModule } from './drafts.js';
+import { type OrderFieldsModule } from './fields.js';
 import { type OrderGetModule } from './get.js';
+import { type OrderLifecycleModule } from './lifecycle.js';
 import { type OrderLinePricePreviewModule } from './line-price-preview.js';
+import { type OrderListModule } from './list.js';
 import { type ManualDiscountsModule } from './manual-discounts.js';
 import { type OrderManualPricingModule } from './manual-pricing.js';
 import { type OrderEntryModule } from './order-entry.js';
 import { type OrderParcelChargeModule } from './parcel-charge.js';
 import { type OrderPlanEditModule } from './plan-edit.js';
+import { type OrderSettingsModule } from './settings.js';
 import { type OrderStatusModule } from './status.js';
 import { type SurchargesModule } from './surcharges.js';
 export type { PaidOrder } from '../payments/index.js';
+export type { OrderBulkAction, OrderBulkCapture, OrderBulkInput, OrderBulkItem, OrderBulkRun, } from './bulk.js';
+export { MAX_BULK_ORDERS, ORDER_BULK_ACTIONS, ORDER_BULK_TRANSITION_REFUSED } from './bulk.js';
+export type { OrderDepositPolicy, OrderDepositPolicyModule, StorefrontDepositPolicy, } from './deposit-policy.js';
+export type { ClonedDraft, DraftAddLineInput, DraftAddressDefault, DraftAddressDefaults, DraftAddressFields, DraftAddressInput, DraftAddressSide, DraftAdjustLineInput, DraftCloneSkipReason, DraftCouponsModule, DraftLinePriceInput, DraftMinimumModule, DraftMinimumStatus, DraftOrder, DraftOrderFields, DraftOrderLine, DraftPaymentInput, DraftRepriceOutcome, DraftShippingQuote, KeyedDraftCall, OrderDraftsModule, PlaceDraftInput, PlacedDraftOrder, PlacedDraftPayment, SaveDraftAddressesInput, SavedDraftAddresses, } from './drafts.js';
+export { DraftInsufficientStockError } from './drafts.js';
+export type { FulfillmentQuantityCorrection, FulfillmentQuantityCorrectionInput, FulfillmentQuantityCorrectionLine, FulfillmentUnitDisposition, OrderCustomerAssignment, OrderFieldsModule, OrderGoodwillRounding, OrderNote, OrderNoteInput, OrderNotesModule, OrderPurchaseOrderNumber, } from './fields.js';
+export type { FulfillmentHoldInput, OrderLifecycleModule, OrderLifecycleRecord, } from './lifecycle.js';
+export type { OrderListFilter, OrderListModule, OrderListOptions, OrderListSort, OrderListSortField, OrderSummary, RecentOrder, RecentOrderLine, RecentOrdersOptions, } from './list.js';
+export { MAX_ORDER_LIST_TAKE, MAX_RECENT_ORDERS, ORDER_LIST_SORT_FIELDS } from './list.js';
 export type { DiscountPolicy, DiscountPolicyInput, DiscountPolicyModule, DiscountReason, DiscountReasonInput, DiscountReasonsModule, ManualDiscountsModule, OrderManualDiscount, } from './manual-discounts.js';
 export type { ExternalLinePriceBasis, ExternalOrder, ExternalOrderAddressInput, ExternalOrderCall, ExternalOrderCatalogLine, ExternalOrderExternalLine, ExternalOrderFulfilment, ExternalOrderInput, ExternalOrderLine, ExternalOrderLineInput, ExternalOrderSurcharge, ExternalOrderSurchargeInput, ExternalOrderTargetState, ExternalOrderTaxLine, } from './order-entry.js';
+export type { MinimumAgeSource, OrderSettings, OrderSettingsModule, OrderStatusRule, OrderStatusRuleConditionType, OrderStatusRuleTargetState, UpdateOrderSettingsInput, } from './settings.js';
+export { MINIMUM_AGE_MAX, MINIMUM_AGE_MIN, ORDER_CODE_DIGITS_MAX, ORDER_CODE_DIGITS_MIN, ORDER_CODE_PREFIX_MAX_LENGTH, ORDER_SETTINGS_AMOUNT_MAX, ORDER_STATUS_RULE_CONDITION_TYPES, ORDER_STATUS_RULE_TARGET_STATES, } from './settings.js';
 /** An app provider an order is running without (`admin.orders.providerFallbacks`). */
 export interface OrderProviderFallback {
     /** `shipping.rates` or `tax.calculate`. */
@@ -64,8 +84,14 @@ export interface OrderSettlement {
  * The manual pricing doors (`setLinePrices`, `setOneTimeDiscounts`) sit there too, beside their
  * read twin `previewLinePrices`, which prices the same changes without saving them.
  */
-export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderParcelChargeModule, OrderLinePricePreviewModule, OrderManualPricingModule, OrderPlanEditModule, OrderCommitEditModule, OrderStatusModule {
+export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderListModule, OrderParcelChargeModule, OrderLinePricePreviewModule, OrderManualPricingModule, OrderPlanEditModule, OrderCommitEditModule, OrderCancelWithMoneyModule, OrderLifecycleModule, OrderFieldsModule, OrderStatusModule {
     surcharges: SurchargesModule;
+    /**
+     * The draft-order builder: staff create a draft, set its customer, lines (with manual prices
+     * and reasons), fields, shipping and order-minimum override, and re-price it, one step at a
+     * time (headless W10-21). See {@link OrderDraftsModule}.
+     */
+    drafts: OrderDraftsModule;
     /**
      * Manual discounts with a reason (incentives spec §4 decision 6): read an order's records,
      * and the store's reason list and policy (`reasons`, `policy`). A discount itself is given
@@ -73,6 +99,93 @@ export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderPar
      * `setOneTimeDiscounts` on this module.
      */
     manualDiscounts: ManualDiscountsModule;
+    /**
+     * Move, cancel, delete or mark paid up to `MAX_BULK_ORDERS` (50) orders of the store in ONE
+     * call (headless spec §7 `orders.bulk`; rulings G19, G28).
+     *
+     * **The run is a job.** The call answers a receipt (`runId`) once the run is queued;
+     * `handle.wait()` polls it until it ends and resolves with the run, whatever the ending.
+     * `bulkRun(runId)` reads it again later, from any process. Each order's outcome is in
+     * `run.items`, in the order the ids were named.
+     *
+     * **Each order is judged as on its own page, and succeeds or fails alone.** First by its own
+     * status (`orders.status`): an action the order's status does not offer, or a TRANSITION target
+     * outside the order's own `nextStates`, answers `ORDER_ACTION_UNAVAILABLE` with `reasonCode`
+     * (that read's vocabulary), before anything is written. Then by its single door, under the
+     * door's own lock, with the door's own code: `ORDER_STATE_TRANSITION_ERROR` (and core's other
+     * order codes), `ORDER_CART_NOT_CANCELLABLE`, `ORDER_UNITS_SHIPPED`,
+     * `ORDER_HAS_ACTIVE_FULFILLMENT`, `ORDER_CANCEL_CREDIT_NOTE_CONFLICT`, `ORDER_HOLDS_MONEY`,
+     * `ORDER_INVOICE_LOCKED`, `ORDER_HAS_RECORDS`, `ORDER_NOT_DELETED`. Another store's order
+     * answers `ENTITY_NOT_FOUND` on its item. A `SUCCEEDED` run can hold `FAILED` items: read them.
+     *
+     * - `TRANSITION` (`toState` required): as `transitionOrderToState`. Never `Cancelled` (use
+     *   `CANCEL`), `PaymentSettled` (use `MARK_PAID`), `Modifying` or `AddingItems`.
+     * - `CANCEL` (`reason` optional): the whole order, shipping included, as `cancelOrder`. **It
+     *   moves no money:** an order that has been placed or parked and still holds money (settled
+     *   money, a card hold) answers `ORDER_HOLDS_MONEY` and is not cancelled; cancel it on its own
+     *   with `orders.cancelWithMoney`, which decides what happens to the money. An INVOICED order,
+     *   paid or not, is not cancelled by either (reason `CREDIT_NOTE_REQUIRED`): do what
+     *   `orders.status`'s `cancelCreditNote.remedy` says first (correct the invoice, or refund the
+     *   payment whose AR credit note corrects it, never both), then cancel it. A credential
+     *   restricted to stock locations (`locationIds`) cancels only an order whose stock is reserved
+     *   at its own locations; any other item answers `LOCATION_OUT_OF_SCOPE`, as `cancelOrder` does.
+     * - `DELETE`: a draft or a cart holding no payment or stock movement, as `deleteOrder`.
+     * - `MARK_PAID`: **captures** each payment of the order that is `Authorized` when the run reaches
+     *   it, read by the engine (never your list's copy), each as `settlePayment` and on its own
+     *   (ruling G19). Each order's `captured` lists every payment acted on. **A decline is a result,
+     *   not a retry:** the order answers `SETTLE_PAYMENT_ERROR`, the payment keeps the state the
+     *   provider left, and the run never asks again. **An unknown provider answer must be
+     *   reconciled, never retried blind:** `IDEMPOTENCY_OUTCOME_UNKNOWN` means the provider was asked
+     *   and its answer was lost; check the payment with the provider. `IDEMPOTENCY_IN_PROGRESS` means
+     *   a capture under the same request may still be running. An order with no authorized payment
+     *   answers `NOTHING_TO_CAPTURE`: it is never marked paid without money (ruling G28).
+     *
+     * **Idempotency.** `options.idempotencyKey` (minted when omitted): the same key with the same
+     * input answers the SAME run, so a resubmit never captures twice; another input under the key is
+     * `IDEMPOTENCY_CONFLICT` (409 `ConflictError`). Each order, and each capture, is keyed within the
+     * run, so a run the platform processes again (a worker restart) answers what it already did from
+     * that record and never asks a provider twice.
+     *
+     * **No dry run.** The refusals that matter are the doors' own, made under their locks, so a
+     * rehearsal could answer "ok" for an order the real run refuses.
+     *
+     * Needs `UpdateOrder` (`DeleteOrder` for `DELETE`); reading the run needs `ReadOrder`. Refusals
+     * of the call itself (nothing is queued): `BULK_ACTION_INPUT_INVALID` (`ValidationError`, 400:
+     * no orders, more than 50, one named twice, an unknown action, a missing or refused `toState`,
+     * an option the action takes none of; refused before sending too), `BULK_ACTION_NOT_ALLOWED`
+     * (`PermissionDeniedError`, 403), `IDEMPOTENCY_CONFLICT`.
+     *
+     * Platform releases before this method do not have the mutation and refuse it as
+     * `ValidationError` `GRAPHQL_VALIDATION_FAILED` (400): deploy the engine first.
+     */
+    bulk(input: OrderBulkInput, options?: Call): Promise<JobHandle<OrderBulkRun>>;
+    /**
+     * One read of a bulk order run, by the `runId` `bulk()` answered. A run of another store, or one
+     * that does not exist, is `BULK_ACTION_RUN_NOT_FOUND` (`NotFoundError`, 404).
+     */
+    bulkRun(runId: string, options?: Call): Promise<OrderBulkRun>;
+    /**
+     * Delete ONE order: a draft or a cart (`AddingItems`) holding no payment and no stock movement,
+     * as the order page's Delete (ruling G29). Needs `DeleteOrder`. Anything else is kept:
+     * `ORDER_INVOICE_LOCKED` (an invoiced order, for every caller), `ORDER_HAS_RECORDS` (cancel it
+     * instead: `orders.bulk` with `CANCEL`), or `ORDER_NOT_DELETED` (`ConflictError`, 409, as every `*_NOT_DELETED` of this SDK) with
+     * the engine's own reason for an order in another state, or one this store does not have.
+     * Placed orders are cancelled, never deleted.
+     */
+    delete(orderId: string, options?: Call): Promise<void>;
+    /**
+     * The store's deposit policy (`orderDepositPolicy`): whether staff may take a
+     * deposit and {@link OrdersModule.park} an order, the minimum a deposit must be,
+     * and whether a shopper may pay one at checkout. `get` answers what the engine
+     * applies; `set` replaces it, validated against the schema's bounds first.
+     */
+    depositPolicy: OrderDepositPolicyModule;
+    /**
+     * The store's order settings (Settings → Orders): the order minimum and its exemptions, order
+     * numbering, the minimum purchase age, the status rules and the outstanding-balance tiers.
+     * `get` answers them as the engine applies them; `set` changes the keys a patch names.
+     */
+    settings: OrderSettingsModule;
     /**
      * Hold a placed order while the rest of its money is arranged. Needs
      * `UpdateOrder`.
@@ -128,7 +241,12 @@ export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderPar
      * position.
      */
     unpark(orderId: string, options?: Call): Promise<PaidOrder>;
-    /** What the order has actually been paid. Needs `ReadOrder`. */
+    /**
+     * What the order has actually been paid, what its credit notes took off and what it still owes
+     * (`payments.position`'s answer). Needs `ReadOrder`.
+     *
+     * @effect read
+     */
     paymentPosition(orderId: string, options?: Call): Promise<OrderPaymentPosition>;
     /**
      * Move a fully paid order to `PaymentSettled`. Needs `UpdateOrder`.
@@ -155,8 +273,10 @@ export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderPar
      * is covered only by an AUTHORIZED payment owes nothing and is refused
      * `COVERAGE_INSUFFICIENT` with the hold kept: accept it by capturing that
      * payment with `settlePayment`, which settles and places it. To turn the order
-     * down, refund the payment, then {@link OrdersModule.unpark} and cancel it: a
-     * refund alone leaves it parked, held and holding its stock.
+     * down, cancel it with {@link OrdersModule.cancelWithMoney}: one call, straight
+     * out of the park, that refunds its money, credits it to the customer's account
+     * or keeps it (with a reason), and gives the reserved stock back. A refund alone
+     * leaves it parked, held and holding its stock.
      *
      * Calling this on an order the platform ALREADY settled succeeds rather than
      * refusing. Expect that to be the common case: the engine settles an order as
@@ -187,5 +307,5 @@ export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderPar
 export declare const PARK_ORDER_MUTATION = "\n  mutation ParkOrder($orderId: ID!, $reason: String, $idempotencyKey: String) {\n    parkOrder(orderId: $orderId, reason: $reason, idempotencyKey: $idempotencyKey) {\n      id\n      code\n      state\n      currencyCode\n      total\n      totalWithTax\n    }\n  }\n";
 export declare const UNPARK_ORDER_MUTATION = "\n  mutation UnparkOrder($orderId: ID!, $idempotencyKey: String) {\n    unparkOrder(orderId: $orderId, idempotencyKey: $idempotencyKey) {\n      id\n      code\n      state\n      currencyCode\n      total\n      totalWithTax\n    }\n  }\n";
 export declare const SETTLE_ORDER_MUTATION = "\n  mutation SettleOrder($orderId: ID!, $fulfil: Boolean!, $idempotencyKey: String) {\n    settleOrder(orderId: $orderId, fulfil: $fulfil, idempotencyKey: $idempotencyKey) {\n      \n  order {\n    id\n    code\n    state\n    currencyCode\n    total\n    totalWithTax\n  }\n  position {\n    total\n    covered\n    settled\n    authorized\n    refunded\n    outstanding\n    overpaid\n    availableToCharge\n  }\n  fulfilRequested\n\n    }\n  }\n";
-export declare const ORDER_POSITION_QUERY = "\n  query OrderPosition($orderId: ID!) {\n    orderPaymentPosition(orderId: $orderId) {\n      total\n      covered\n      settled\n      authorized\n      refunded\n      outstanding\n      overpaid\n      availableToCharge\n    }\n  }\n";
+export declare const ORDER_POSITION_QUERY = "\n  query OrderPosition($orderId: ID!) {\n    orderPaymentPosition(orderId: $orderId) {\n      total\n      covered\n      settled\n      authorized\n      refunded\n      creditNoted\n      owed\n      outstanding\n      overpaid\n      availableToCharge\n    }\n  }\n";
 export declare function createOrdersModule(transport: Transport): OrdersModule;

package/dist/orders/index.js

@@ -1,14 +1,27 @@
 import { NotFoundError } from '@sixtyninecommerce/core';
+import { creditNotedAware } from '../payments/credit-noted-fields.js';
+import { bulkOrders, deleteOrder, readOrderBulkRun, } from './bulk.js';
+import { createOrderCancelWithMoneyModule, } from './cancel-with-money.js';
 import { createOrderCommitEditModule } from './commit-edit.js';
+import { createOrderDepositPolicyModule } from './deposit-policy.js';
+import { createOrderDraftsModule } from './drafts.js';
+import { createOrderFieldsModule } from './fields.js';
 import { createOrderGetModule } from './get.js';
+import { createOrderLifecycleModule } from './lifecycle.js';
 import { createOrderLinePricePreviewModule, } from './line-price-preview.js';
+import { createOrderListModule } from './list.js';
 import { createManualDiscountsModule } from './manual-discounts.js';
 import { createOrderManualPricingModule } from './manual-pricing.js';
 import { createOrderEntryModule } from './order-entry.js';
 import { createOrderParcelChargeModule } from './parcel-charge.js';
 import { createOrderPlanEditModule } from './plan-edit.js';
+import { createOrderSettingsModule } from './settings.js';
 import { createOrderStatusModule } from './status.js';
 import { createSurchargesModule } from './surcharges.js';
+export { MAX_BULK_ORDERS, ORDER_BULK_ACTIONS, ORDER_BULK_TRANSITION_REFUSED } from './bulk.js';
+export { DraftInsufficientStockError } from './drafts.js';
+export { MAX_ORDER_LIST_TAKE, MAX_RECENT_ORDERS, ORDER_LIST_SORT_FIELDS } from './list.js';
+export { MINIMUM_AGE_MAX, MINIMUM_AGE_MIN, ORDER_CODE_DIGITS_MAX, ORDER_CODE_DIGITS_MIN, ORDER_CODE_PREFIX_MAX_LENGTH, ORDER_SETTINGS_AMOUNT_MAX, ORDER_STATUS_RULE_CONDITION_TYPES, ORDER_STATUS_RULE_TARGET_STATES, } from './settings.js';
 const ORDER_PROVIDER_FALLBACKS_QUERY = /* GraphQL */ `
   query OrderProviderFallbacks($id: ID!) {
     order(id: $id) {
@@ -82,6 +95,8 @@ export const ORDER_POSITION_QUERY = /* GraphQL */ `
       settled
       authorized
       refunded
+      creditNoted
+      owed
       outstanding
       overpaid
       availableToCharge
@@ -89,17 +104,34 @@ export const ORDER_POSITION_QUERY = /* GraphQL */ `
   }
 `;
 export function createOrdersModule(transport) {
+    const getModule = createOrderGetModule(transport);
     return {
         ...createOrderEntryModule(transport),
-        ...createOrderGetModule(transport),
+        ...getModule,
+        ...createOrderListModule(transport),
         ...createOrderParcelChargeModule(transport),
         ...createOrderLinePricePreviewModule(transport),
         ...createOrderManualPricingModule(transport),
         ...createOrderPlanEditModule(transport),
         ...createOrderCommitEditModule(transport),
+        ...createOrderCancelWithMoneyModule(transport),
+        ...createOrderLifecycleModule(transport),
+        ...createOrderFieldsModule(transport),
         ...createOrderStatusModule(transport),
         surcharges: createSurchargesModule(transport),
+        drafts: createOrderDraftsModule(transport, getModule),
         manualDiscounts: createManualDiscountsModule(transport),
+        depositPolicy: createOrderDepositPolicyModule(transport),
+        settings: createOrderSettingsModule(transport),
+        bulk(input, options) {
+            return bulkOrders(transport, input, options);
+        },
+        bulkRun(runId, options) {
+            return readOrderBulkRun(transport, runId, options);
+        },
+        delete(orderId, options) {
+            return deleteOrder(transport, orderId, options);
+        },
         async park(orderId, options) {
             const data = await transport.graphql({
                 api: 'admin',
@@ -137,7 +169,8 @@ export function createOrdersModule(transport) {
             return data.order.providerFallbacks;
         },
         async paymentPosition(orderId, options) {
-            const data = await transport.graphql({ api: 'admin', query: ORDER_POSITION_QUERY, variables: { orderId } }, options);
+            // The credit fields fall away on an engine before them: the position itself still reads.
+            const data = await creditNotedAware(transport).graphql({ api: 'admin', query: ORDER_POSITION_QUERY, variables: { orderId } }, options);
             return data.orderPaymentPosition;
         },
         async settle(orderId, options) {

package/dist/orders/lifecycle.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The single-order lifecycle writes (headless spec §9.2 `orders`, "holds, cancel/reopen/complete";
+ * W10-25): complete, reopen, waive the payment, hold the fulfilment, move the order to another
+ * state, and cancel it whole.
+ *
+ * Which of them an order allows now, and why not, is `orders.status(orderId).actions`
+ * (`MARK_COMPLETED`, `REOPEN`, `SET_PAYMENT_NOT_REQUIRED`, `SET_FULFILLMENT_HOLD`, `TRANSITION`
+ * with `nextStates`, `CANCEL`): ask it before offering one. Every refusal below is a coded
+ * `PlatformError`; core's own transition refusals carry the gate's reason as their message, never
+ * Vendure's "Cannot transition Order from X to Y" template.
+ */
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+import type { OrderFulfillmentHoldReason } from './get.js';
+/** The order as a lifecycle write leaves it. */
+export interface OrderLifecycleRecord {
+    id: string;
+    code: string;
+    /** The engine state. */
+    state: string;
+    /**
+     * The four projected dimensions (`orders.status` reads the same). Each is null on an order that
+     * predates them, and for a moment after a change: the engine writes them after the change.
+     */
+    lifecycle: {
+        status: string | null;
+        payment: string | null;
+        fulfillment: string | null;
+        return: string | null;
+    };
+}
+/** Putting a hold on (`hold: true`, with a reason) or releasing it (`hold: false`, nothing else). */
+export type FulfillmentHoldInput = {
+    hold: true;
+    reason: OrderFulfillmentHoldReason;
+    /** At most 500 characters. Required for `other`. */
+    note?: string | null;
+} | {
+    hold: false;
+};
+export interface OrderLifecycleModule {
+    /**
+     * Mark the order completed. Needs `UpdateOrder`.
+     *
+     * Refused `ORDER_ALREADY_COMPLETED` on a completed order and `ORDER_COMPLETE_CANCELLED` on a
+     * cancelled one (`BusinessRuleError`, 422); nothing changes. Against an engine older than these
+     * codes the same call succeeded without changing anything.
+     *
+     * @effect write
+     */
+    markCompleted(orderId: string, options?: Call): Promise<OrderLifecycleRecord>;
+    /**
+     * Reopen a completed order. Needs `UpdateOrder`. Does nothing to an order that is not
+     * completed. Refused `ORDER_REOPEN_LOCKED` (422) while an invoice locks the order: an invoiced
+     * order is corrected by void & reissue, not reopened.
+     *
+     * @effect write
+     */
+    reopen(orderId: string, options?: Call): Promise<OrderLifecycleRecord>;
+    /**
+     * Waive the payment the order expects (`notRequired: true`: a comp, a sample) or lift the
+     * waiver (`false`). The payment dimension reads `not_required` while waived. Needs
+     * `UpdateOrder`.
+     *
+     * Refused `ORDER_PAYMENT_WAIVER_REFUSED` (422) on a cancelled order either way, and when
+     * waiving an order an invoice still bills: correct the invoice first (`orders.status` answers
+     * `CREDIT_NOTE_REQUIRED`). Lifting a waiver is otherwise never refused.
+     *
+     * @effect money
+     */
+    setPaymentNotRequired(orderId: string, notRequired: boolean, options?: Call): Promise<OrderLifecycleRecord>;
+    /**
+     * Put the order's fulfilment on hold with a reason, or release it. Re-holding replaces the
+     * reason and note. Both directions write a private (staff-only) history entry. Needs
+     * `UpdateOrder`.
+     *
+     * Refused `ORDER_FULFILLMENT_HOLD_INVALID` (`ValidationError`, 400) for an unknown reason, a
+     * note over 500 characters, or `other` without a note. `orders.status` offers a NEW hold on an
+     * open order only (`SET_FULFILLMENT_HOLD`), and a release on any order holding one.
+     *
+     * @effect write
+     */
+    setFulfillmentHold(orderId: string, input: FulfillmentHoldInput, options?: Call): Promise<OrderLifecycleRecord>;
+    /**
+     * Move the order to one of `orders.status(orderId).nextStates`. Needs `UpdateOrder`.
+     *
+     * A move into `PaymentSettled`, or into `PaymentAuthorized` from the unpaid side, is refused
+     * `COVERAGE_INSUFFICIENT` (422) while the order's money does not cover it (settled money for
+     * `PaymentSettled`; a net-terms order is judged when it was authorized): it never settles an
+     * order without its money (`nextStates` already leaves such a move out). A move into
+     * `Cancelled` is a cancel, and refused as {@link OrderLifecycleModule.cancel} is. Any other
+     * refusal is core's `ORDER_STATE_TRANSITION_ERROR` with the gate's reason as its message (an
+     * order minimum, unconfirmed terms, a stock shortage).
+     *
+     * @effect money
+     */
+    transition(orderId: string, state: string, options?: Call): Promise<OrderLifecycleRecord>;
+    /**
+     * Cancel the WHOLE order, shipping included. An order cannot be un-cancelled. Needs
+     * `UpdateOrder`. Lines alone are cancelled through `orders.commitEdit`.
+     *
+     * It moves no money. Refused:
+     * - `ORDER_HOLDS_MONEY` (422) while the order has been placed or parked and still holds money:
+     *   use `orders.cancelWithMoney`, which decides what happens to it;
+     * - `ORDER_CANCEL_CREDIT_NOTE_CONFLICT` (409) while an invoice still bills the order, paid or
+     *   not: do what `orders.status(orderId).cancelCreditNote.remedy` says first;
+     * - `ORDER_UNITS_SHIPPED` / `ORDER_HAS_ACTIVE_FULFILLMENT` (422) while a fulfilment holds a
+     *   line; `ORDER_CART_NOT_CANCELLABLE` (422) for a live cart the store may not end;
+     * - `LOCATION_OUT_OF_SCOPE` (422), for a credential restricted to stock locations (an API
+     *   token or app installation with `locationIds`) only: the order's stock is reserved at a
+     *   location outside its restriction, and a cancel releases it there
+     *   (`orders.status(orderId)` answers `CANCEL` with `PERMISSION`);
+     * - core's own refusals (`ORDER_STATE_TRANSITION_ERROR`, `CANCEL_ACTIVE_ORDER_ERROR`,
+     *   `EMPTY_ORDER_LINE_SELECTION_ERROR`) with their reason.
+     *
+     * @effect irreversible
+     */
+    cancel(orderId: string, options?: Call & {
+        reason?: string;
+    }): Promise<OrderLifecycleRecord>;
+}
+export declare const MARK_ORDER_COMPLETED_MUTATION = "\n  mutation MarkOrderCompleted($orderId: ID!) {\n    markOrderCompleted(orderId: $orderId) {\n      \n  id\n  code\n  state\n  customFields {\n    lifecycleStatus\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n  }\n\n    }\n  }\n";
+export declare const REOPEN_ORDER_MUTATION = "\n  mutation ReopenOrder($orderId: ID!) {\n    reopenOrder(orderId: $orderId) {\n      \n  id\n  code\n  state\n  customFields {\n    lifecycleStatus\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n  }\n\n    }\n  }\n";
+export declare const MARK_ORDER_PAYMENT_NOT_REQUIRED_MUTATION = "\n  mutation MarkOrderPaymentNotRequired($orderId: ID!, $notRequired: Boolean!) {\n    markOrderPaymentNotRequired(orderId: $orderId, notRequired: $notRequired) {\n      \n  id\n  code\n  state\n  customFields {\n    lifecycleStatus\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n  }\n\n    }\n  }\n";
+export declare const SET_ORDER_FULFILLMENT_HOLD_MUTATION = "\n  mutation SetOrderFulfillmentHold(\n    $orderId: ID!\n    $onHold: Boolean!\n    $reason: FulfillmentHoldReason\n    $note: String\n  ) {\n    setOrderFulfillmentHold(orderId: $orderId, onHold: $onHold, reason: $reason, note: $note) {\n      \n  id\n  code\n  state\n  customFields {\n    lifecycleStatus\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n  }\n\n    }\n  }\n";
+export declare const TRANSITION_ORDER_MUTATION = "\n  mutation TransitionOrderToState($id: ID!, $state: String!) {\n    transitionOrderToState(id: $id, state: $state) {\n      __typename\n      ... on Order {\n        \n  id\n  code\n  state\n  customFields {\n    lifecycleStatus\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n  }\n\n      }\n      ... on OrderStateTransitionError {\n        transitionError\n      }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
+export declare const CANCEL_ORDER_MUTATION = "\n  mutation CancelOrder($input: CancelOrderInput!) {\n    cancelOrder(input: $input) {\n      __typename\n      ... on Order {\n        \n  id\n  code\n  state\n  customFields {\n    lifecycleStatus\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n  }\n\n      }\n      ... on OrderStateTransitionError {\n        transitionError\n      }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
+export declare function createOrderLifecycleModule(transport: Transport): OrderLifecycleModule;

package/dist/orders/lifecycle.js

@@ -0,0 +1,158 @@
+/**
+ * The single-order lifecycle writes (headless spec §9.2 `orders`, "holds, cancel/reopen/complete";
+ * W10-25): complete, reopen, waive the payment, hold the fulfilment, move the order to another
+ * state, and cancel it whole.
+ *
+ * Which of them an order allows now, and why not, is `orders.status(orderId).actions`
+ * (`MARK_COMPLETED`, `REOPEN`, `SET_PAYMENT_NOT_REQUIRED`, `SET_FULFILLMENT_HOLD`, `TRANSITION`
+ * with `nextStates`, `CANCEL`): ask it before offering one. Every refusal below is a coded
+ * `PlatformError`; core's own transition refusals carry the gate's reason as their message, never
+ * Vendure's "Cannot transition Order from X to Y" template.
+ */
+import { errorFromErrorResult, isErrorResult } from '@sixtyninecommerce/core';
+const ORDER_FIELDS = /* GraphQL */ `
+  id
+  code
+  state
+  customFields {
+    lifecycleStatus
+    paymentStatus
+    fulfillmentStatus
+    returnStatus
+  }
+`;
+export const MARK_ORDER_COMPLETED_MUTATION = /* GraphQL */ `
+  mutation MarkOrderCompleted($orderId: ID!) {
+    markOrderCompleted(orderId: $orderId) {
+      ${ORDER_FIELDS}
+    }
+  }
+`;
+export const REOPEN_ORDER_MUTATION = /* GraphQL */ `
+  mutation ReopenOrder($orderId: ID!) {
+    reopenOrder(orderId: $orderId) {
+      ${ORDER_FIELDS}
+    }
+  }
+`;
+export const MARK_ORDER_PAYMENT_NOT_REQUIRED_MUTATION = /* GraphQL */ `
+  mutation MarkOrderPaymentNotRequired($orderId: ID!, $notRequired: Boolean!) {
+    markOrderPaymentNotRequired(orderId: $orderId, notRequired: $notRequired) {
+      ${ORDER_FIELDS}
+    }
+  }
+`;
+export const SET_ORDER_FULFILLMENT_HOLD_MUTATION = /* GraphQL */ `
+  mutation SetOrderFulfillmentHold(
+    $orderId: ID!
+    $onHold: Boolean!
+    $reason: FulfillmentHoldReason
+    $note: String
+  ) {
+    setOrderFulfillmentHold(orderId: $orderId, onHold: $onHold, reason: $reason, note: $note) {
+      ${ORDER_FIELDS}
+    }
+  }
+`;
+// The concrete members are selected for their sentences: `ErrorResult.message` is a per-code
+// template, and the refusing gate's reason lives on the concrete type alone.
+export const TRANSITION_ORDER_MUTATION = /* GraphQL */ `
+  mutation TransitionOrderToState($id: ID!, $state: String!) {
+    transitionOrderToState(id: $id, state: $state) {
+      __typename
+      ... on Order {
+        ${ORDER_FIELDS}
+      }
+      ... on OrderStateTransitionError {
+        transitionError
+      }
+      ... on ErrorResult {
+        errorCode
+        message
+      }
+    }
+  }
+`;
+export const CANCEL_ORDER_MUTATION = /* GraphQL */ `
+  mutation CancelOrder($input: CancelOrderInput!) {
+    cancelOrder(input: $input) {
+      __typename
+      ... on Order {
+        ${ORDER_FIELDS}
+      }
+      ... on OrderStateTransitionError {
+        transitionError
+      }
+      ... on ErrorResult {
+        errorCode
+        message
+      }
+    }
+  }
+`;
+function recordOf(order) {
+    const fields = order.customFields ?? {};
+    return {
+        id: order.id,
+        code: order.code,
+        state: order.state,
+        lifecycle: {
+            status: fields.lifecycleStatus ?? null,
+            payment: fields.paymentStatus ?? null,
+            fulfillment: fields.fulfillmentStatus ?? null,
+            return: fields.returnStatus ?? null,
+        },
+    };
+}
+/** The order, or the union member thrown as a coded error carrying the gate's own reason. */
+function orderOrThrow(result) {
+    if (!isErrorResult(result))
+        return recordOf(result);
+    const reason = result.transitionError;
+    const message = typeof reason === 'string' && reason.trim() !== '' ? reason : result.message;
+    throw errorFromErrorResult({ errorCode: result.errorCode, message });
+}
+export function createOrderLifecycleModule(transport) {
+    const write = async (field, query, variables, options) => {
+        const data = await transport.graphql({ api: 'admin', query, variables }, options);
+        return recordOf(data[field]);
+    };
+    return {
+        markCompleted(orderId, options) {
+            return write('markOrderCompleted', MARK_ORDER_COMPLETED_MUTATION, { orderId }, options);
+        },
+        reopen(orderId, options) {
+            return write('reopenOrder', REOPEN_ORDER_MUTATION, { orderId }, options);
+        },
+        setPaymentNotRequired(orderId, notRequired, options) {
+            return write('markOrderPaymentNotRequired', MARK_ORDER_PAYMENT_NOT_REQUIRED_MUTATION, { orderId, notRequired }, options);
+        },
+        setFulfillmentHold(orderId, input, options) {
+            // A release sends neither a reason nor a note: the engine refuses them there.
+            const variables = input.hold
+                ? { orderId, onHold: true, reason: input.reason, note: input.note ?? null }
+                : { orderId, onHold: false };
+            return write('setOrderFulfillmentHold', SET_ORDER_FULFILLMENT_HOLD_MUTATION, variables, options);
+        },
+        async transition(orderId, state, options) {
+            const data = await transport.graphql({ api: 'admin', query: TRANSITION_ORDER_MUTATION, variables: { id: orderId, state } }, options);
+            const result = data.transitionOrderToState;
+            if (!result) {
+                throw errorFromErrorResult({
+                    errorCode: 'ORDER_NOT_FOUND',
+                    message: `This store has no order ${orderId}.`,
+                });
+            }
+            return orderOrThrow(result);
+        },
+        async cancel(orderId, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: CANCEL_ORDER_MUTATION,
+                // `undefined`, never an explicit null: an omitted reason stays off the wire.
+                variables: { input: { orderId, reason: options?.reason, cancelShipping: true } },
+            }, options);
+            return orderOrThrow(data.cancelOrder);
+        },
+    };
+}

package/dist/orders/line-price-preview.d.ts

@@ -224,8 +224,8 @@ export interface OrderLinePricePreviewModule {
      * validated, tax removed) does not show in such a line's figures, so the
      * comparison above does not see it.
      *
-     * The preview does not
-     * predict what a save refuses: a staged one-time discount that the Admin
+     * Apart from the clears listed under the refusals below, the preview does
+     * not predict what a save refuses: a staged one-time discount that the Admin
      * API's `setOrderPriceListDiscounts` would refuse is still priced, and shows
      * no `ONE_TIME` step when the pricing rules skipped it.
      *
@@ -289,6 +289,11 @@ export interface OrderLinePricePreviewModule {
      *   preview does not evaluate (`PreviewLinePriceOverride.basis`).
      * - `PREVIEW_CHANNEL_NOT_ALLOWED` (`PermissionDeniedError`, 403): the call
      *   was made from the default channel instead of the order's own.
+     * - `ORDER_LINE_VARIANT_UNPRICED` (`BusinessRuleError`, 422; absent from an
+     *   engine released before 2026-10-10): `override: null` on a line that
+     *   states a manual price while its variant has no price in the store, as
+     *   the save refuses it; stage the price you want, or set a price for the
+     *   variant in the store first.
      */
     previewLinePrices(orderId: string, lines: PreviewLinePriceLine[], options?: Call & {
         orderDiscount?: PreviewOneTimeDiscount | null;