@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/orders/settings.js

@@ -0,0 +1,325 @@
+import { errorFromErrorResult, isErrorResult, NotFoundError, ValidationError, } from '@sixtyninecommerce/core';
+// Mirrors, pinned by `__tests__/order-settings.spec.ts`: the engine's `VALID_TARGET_STATES` /
+// `VALID_CONDITION_TYPES` (`order-constraints/order-status-rules-process.ts`) and the shared
+// `ORDER_STATUS_RULE_*` the meta catalog publishes; `ORDER_CODE_DIGITS_MIN/MAX` in
+// `order-code/channel-aware-order-code-strategy.ts`. Change both sides together.
+/** The states an order status rule may move a placed order to. */
+export const ORDER_STATUS_RULE_TARGET_STATES = [
+    'AwaitingApproval',
+    'PaymentAuthorized',
+    'PaymentSettled',
+];
+/** What an order status rule matches on. */
+export const ORDER_STATUS_RULE_CONDITION_TYPES = [
+    'product',
+    'coupon',
+    'collection',
+    'facet_value',
+];
+/** The fewest zero-padded digits of a sequential order number. */
+export const ORDER_CODE_DIGITS_MIN = 4;
+/** The most zero-padded digits of a sequential order number. */
+export const ORDER_CODE_DIGITS_MAX = 8;
+/**
+ * The longest order-number prefix. The engine stores more, but every order code is
+ * `NAMESPACE-PREFIX00001` in a 255-character column: a long prefix fails EVERY order placement.
+ */
+export const ORDER_CODE_PREFIX_MAX_LENGTH = 20;
+/** The youngest minimum purchase age (the engine checks no age below 1: `minimumAge > 0`). */
+export const MINIMUM_AGE_MIN = 1;
+/** The oldest minimum purchase age the platform accepts. */
+export const MINIMUM_AGE_MAX = 99;
+/**
+ * The largest amount (minor units) the minimum and the thresholds hold: the columns are Vendure
+ * `int` custom fields, GraphQL `Int` (32 bits). ₩30,000,000 is 3,000,000,000 hundredths, past it.
+ */
+export const ORDER_SETTINGS_AMOUNT_MAX = 2_147_483_647;
+/** The settings group `minimumAge` belongs to (multi-region spec §5.3). */
+const AGE_GROUP = 'settings.age_verification';
+const CHANNEL_FIELDS = /* GraphQL */ `
+  id
+  code
+  defaultCurrencyCode
+  customFields {
+    minOrderAmount
+    exemptCustomerGroupIds
+    exemptCollectionIds
+    orderCodeNamespace
+    orderCodePrefix
+    orderCodeDigits
+    orderCodeEnabled
+    minimumAge
+    orderStatusRules
+    outstandingBalanceWarningThreshold
+    outstandingBalanceCriticalThreshold
+  }
+`;
+export const ORDER_SETTINGS_QUERY = /* GraphQL */ `
+  query OrderSettings {
+    activeChannel { ${CHANNEL_FIELDS} }
+    channelSettingsSources { group source locked overridden inheritable values }
+  }
+`;
+export const UPDATE_ORDER_SETTINGS_MUTATION = /* GraphQL */ `
+  mutation UpdateOrderSettings($input: UpdateChannelInput!) {
+    updateChannel(input: $input) {
+      ... on Channel { ${CHANNEL_FIELDS} }
+      ... on ErrorResult { errorCode message }
+    }
+  }
+`;
+const INVALID = 'ORDER_SETTINGS_INVALID';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isWhole = (value) => typeof value === 'number' && Number.isSafeInteger(value);
+const numberOrNull = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
+const stringOrNull = (value) => (typeof value === 'string' ? value : null);
+/** The non-empty strings of `value`, when it is an array; otherwise none. */
+function strings(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string' && item.length > 0)
+        : [];
+}
+function parsedJson(raw) {
+    if (typeof raw !== 'string' || raw === '')
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * An exemption list as the order-minimum checker reads it: the column's non-empty string ids,
+ * once each; anything unreadable is no exemption.
+ */
+function readIdList(raw) {
+    return [...new Set(strings(parsedJson(raw)))];
+}
+const LIST_OF = {
+    product: 'productVariantIds',
+    coupon: 'couponCodes',
+    collection: 'collectionIds',
+    facet_value: 'facetValueIds',
+};
+const TARGET_STATES = new Set(ORDER_STATUS_RULE_TARGET_STATES);
+const CONDITION_TYPES = new Set(ORDER_STATUS_RULE_CONDITION_TYPES);
+/**
+ * The column as the engine's `parseRules` keeps it: an entry with a string `id`, a known
+ * `targetState` and a known `conditionType`. A rule the engine keeps is never dropped here (a
+ * stricter reader would erase it on the next save, turning off the transition it performs), so
+ * a missing `name` reads `''` and `enabled` reads as the engine takes it (truthy fires). Only the
+ * rule's own keys come back, so the list can be sent back as the engine's schema wants it.
+ */
+export function readOrderStatusRules(raw) {
+    const parsed = parsedJson(raw);
+    if (!Array.isArray(parsed))
+        return [];
+    const rules = [];
+    for (const entry of parsed) {
+        if (!isRecord(entry))
+            continue;
+        const { id, targetState, conditionType } = entry;
+        if (typeof id !== 'string' || !TARGET_STATES.has(targetState))
+            continue;
+        if (!CONDITION_TYPES.has(conditionType))
+            continue;
+        const rule = {
+            id,
+            name: typeof entry.name === 'string' ? entry.name : '',
+            targetState: targetState,
+            conditionType: conditionType,
+            enabled: Boolean(entry.enabled),
+        };
+        for (const list of Object.values(LIST_OF)) {
+            if (Array.isArray(entry[list]))
+                rule[list] = strings(entry[list]);
+        }
+        rules.push(rule);
+    }
+    return rules;
+}
+/** An age the engine checks (`minimumAge > 0`), else none. */
+const checkedAge = (age) => (age !== null && age > 0 ? age : null);
+function sourceOf(sources, own) {
+    const group = sources.find((item) => item.group === AGE_GROUP);
+    if (!group) {
+        return {
+            source: 'channel',
+            locked: false,
+            inheritable: false,
+            overridden: false,
+            effective: checkedAge(own),
+        };
+    }
+    // The store's own value when its own applies: after `set` the sources are the ones read BEFORE
+    // the write, so their values would answer the old age. The organization's values otherwise.
+    const applied = group.source !== 'channel' && group.values ? numberOrNull(group.values.minimumAge) : own;
+    return {
+        source: group.source,
+        locked: group.locked,
+        inheritable: group.inheritable,
+        overridden: group.overridden,
+        effective: checkedAge(applied),
+    };
+}
+function settingsOf(channel, sources) {
+    const fields = channel.customFields ?? {};
+    const minimumAge = numberOrNull(fields.minimumAge);
+    return {
+        channelId: channel.id,
+        currencyCode: channel.defaultCurrencyCode,
+        minOrderAmount: numberOrNull(fields.minOrderAmount),
+        exemptCustomerGroupIds: readIdList(fields.exemptCustomerGroupIds),
+        exemptCollectionIds: readIdList(fields.exemptCollectionIds),
+        orderCodeEnabled: fields.orderCodeEnabled === true,
+        orderCodeNamespace: stringOrNull(fields.orderCodeNamespace) || null,
+        orderCodePrefix: stringOrNull(fields.orderCodePrefix),
+        orderCodeDigits: numberOrNull(fields.orderCodeDigits),
+        minimumAge,
+        minimumAgeSource: sourceOf(sources, minimumAge),
+        orderStatusRules: readOrderStatusRules(fields.orderStatusRules),
+        outstandingBalanceWarningThreshold: numberOrNull(fields.outstandingBalanceWarningThreshold),
+        outstandingBalanceCriticalThreshold: numberOrNull(fields.outstandingBalanceCriticalThreshold),
+    };
+}
+const PATCH_KEYS = [
+    'minOrderAmount',
+    'exemptCustomerGroupIds',
+    'exemptCollectionIds',
+    'orderCodeEnabled',
+    'orderCodePrefix',
+    'orderCodeDigits',
+    'minimumAge',
+    'orderStatusRules',
+    'outstandingBalanceWarningThreshold',
+    'outstandingBalanceCriticalThreshold',
+];
+const KNOWN_KEYS = new Set(PATCH_KEYS);
+const AMOUNT_KEYS = [
+    'minOrderAmount',
+    'outstandingBalanceWarningThreshold',
+    'outstandingBalanceCriticalThreshold',
+];
+const LIST_KEYS = ['exemptCustomerGroupIds', 'exemptCollectionIds', 'orderStatusRules'];
+/** Every way `patch` breaks the input's shape, one entry per key. */
+function problemsOf(patch) {
+    const problems = [];
+    const add = (field, message) => problems.push({ field, code: INVALID, message });
+    if (!isRecord(patch)) {
+        add('patch', 'Pass the settings to change as an object, e.g. { minOrderAmount: 5000 }.');
+        return problems;
+    }
+    const named = Object.keys(patch).filter((key) => patch[key] !== undefined);
+    if (named.length === 0) {
+        add('patch', `Name at least one setting to change: ${PATCH_KEYS.join(', ')}.`);
+    }
+    for (const key of named) {
+        if (KNOWN_KEYS.has(key))
+            continue;
+        add(key, key === 'orderCodeNamespace'
+            ? 'orderCodeNamespace is set by the platform from the store code, never by a caller: switch orderCodeEnabled on and it is set for you.'
+            : `${key} is not an order setting; the settings are ${PATCH_KEYS.join(', ')}.`);
+    }
+    for (const key of AMOUNT_KEYS) {
+        const value = patch[key];
+        if (value === undefined || value === null)
+            continue;
+        if (!(isWhole(value) && value >= 0 && value <= ORDER_SETTINGS_AMOUNT_MAX)) {
+            add(key, `${key} must be a whole number of minor units from 0 to ${String(ORDER_SETTINGS_AMOUNT_MAX)}, or null to clear it.`);
+        }
+    }
+    for (const key of LIST_KEYS) {
+        const value = patch[key];
+        if (value !== undefined && !Array.isArray(value)) {
+            add(key, `${key} must be an array (the whole list); send [] for none.`);
+        }
+    }
+    if (patch.orderCodeEnabled !== undefined && typeof patch.orderCodeEnabled !== 'boolean') {
+        add('orderCodeEnabled', 'orderCodeEnabled must be true or false.');
+    }
+    const prefix = patch.orderCodePrefix;
+    if (prefix !== undefined &&
+        prefix !== null &&
+        !(typeof prefix === 'string' && prefix.length <= ORDER_CODE_PREFIX_MAX_LENGTH)) {
+        add('orderCodePrefix', `orderCodePrefix must be text of at most ${String(ORDER_CODE_PREFIX_MAX_LENGTH)} characters, or null for none.`);
+    }
+    const digits = patch.orderCodeDigits;
+    if (digits !== undefined &&
+        digits !== null &&
+        !(isWhole(digits) && digits >= ORDER_CODE_DIGITS_MIN && digits <= ORDER_CODE_DIGITS_MAX)) {
+        add('orderCodeDigits', `orderCodeDigits must be a whole number from ${String(ORDER_CODE_DIGITS_MIN)} to ${String(ORDER_CODE_DIGITS_MAX)}, or null for the default.`);
+    }
+    const age = patch.minimumAge;
+    if (age !== undefined &&
+        age !== null &&
+        !(isWhole(age) && age >= MINIMUM_AGE_MIN && age <= MINIMUM_AGE_MAX)) {
+        add('minimumAge', `minimumAge must be a whole number of years from ${String(MINIMUM_AGE_MIN)} to ${String(MINIMUM_AGE_MAX)}, or null for no age check.`);
+    }
+    return problems;
+}
+/** A list column as the engine stores it: JSON text, or null for an empty list. */
+const listColumn = (list) => list.length > 0 ? JSON.stringify(list) : null;
+/** The custom fields `patch` writes; `before` is the store as read just before. */
+function customFieldsOf(patch, before) {
+    const fields = {};
+    for (const key of PATCH_KEYS) {
+        const value = patch[key];
+        if (value === undefined)
+            continue;
+        fields[key] = Array.isArray(value) ? listColumn(value) : value;
+    }
+    // Ruling G125: the namespace is the platform's, never the caller's. A store switching
+    // sequential numbers on for the first time gets its code in capitals, which is what
+    // provisioning gives a new store (`provision-store.saga.ts`) and is unique because codes are.
+    const namespace = stringOrNull(before.customFields?.orderCodeNamespace);
+    if (patch.orderCodeEnabled === true && !namespace) {
+        fields.orderCodeNamespace = before.code.toUpperCase();
+    }
+    return fields;
+}
+export function createOrderSettingsModule(transport) {
+    const read = async (options) => {
+        const data = await transport.graphql({ api: 'admin', query: ORDER_SETTINGS_QUERY }, options);
+        if (!data.activeChannel) {
+            throw new NotFoundError({
+                code: 'CHANNEL_NOT_FOUND',
+                message: 'No store is active for this session, so it has no order settings to read.',
+                status: 404,
+                service: 'vendure',
+            });
+        }
+        return { channel: data.activeChannel, sources: data.channelSettingsSources ?? [] };
+    };
+    return {
+        async get(options) {
+            const { channel, sources } = await read(options);
+            return settingsOf(channel, sources);
+        },
+        async set(patch, options) {
+            const problems = problemsOf(patch);
+            if (problems.length > 0) {
+                throw new ValidationError({
+                    code: INVALID,
+                    message: problems.map((problem) => problem.message).join(' '),
+                    status: 400,
+                    service: 'vendure',
+                    details: problems,
+                });
+            }
+            // The id `updateChannel` needs and the namespace rule's "before", read with the SAME call
+            // options, so a per-call tenant writes its own store rather than the client's.
+            const { channel, sources } = await read(options);
+            const data = await transport.graphql({
+                api: 'admin',
+                query: UPDATE_ORDER_SETTINGS_MUTATION,
+                variables: { input: { id: channel.id, customFields: customFieldsOf(patch, channel) } },
+            }, options);
+            if (isErrorResult(data.updateChannel))
+                throw errorFromErrorResult(data.updateChannel);
+            // An order settings write never changes where the age comes from, so the sources read
+            // just before still hold; `sourceOf` takes the new own value when the store's applies.
+            return settingsOf(data.updateChannel, sources);
+        },
+    };
+}

package/dist/orders/status.d.ts

@@ -34,7 +34,7 @@ export type OrderAllocationBadge = (typeof ORDER_ALLOCATION_BADGES)[number];
 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"];
+export declare const ORDER_STATUS_ACTIONS: readonly ["MODIFY", "DELETE", "RELEASE_ALLOCATION", "CORRECT_FULFILLMENT", "CANCEL", "TRANSITION", "MARK_COMPLETED", "REOPEN", "SET_PAYMENT_NOT_REQUIRED", "SET_FULFILLMENT_HOLD", "SET_GOODWILL_ROUNDING", "SET_BILLING_FIELDS", "APPLY_GOODWILL_ROUNDING", "SET_PRICING_FIELDS"];
 /**
  * One thing that can be done to an order, with the engine write behind it and
  * what `allowed` asks of the caller:
@@ -56,14 +56,76 @@ export declare const ORDER_STATUS_ACTIONS: readonly ["MODIFY", "DELETE", "RELEAS
  *   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`.
+ * - `CANCEL`: `cancelOrder` for the whole order. Needs `UpdateOrder`. A credential
+ *   restricted to stock locations must also hold every location the order's
+ *   reservation sits at (a cancel releases it there); otherwise the cancel answers
+ *   `LOCATION_OUT_OF_SCOPE` and this action `PERMISSION`.
  * - `TRANSITION`: `transitionOrderToState` into one of `nextStates`. Needs
  *   `UpdateOrder`.
- * - `MARK_COMPLETED`: `markOrderCompleted`. Needs `UpdateOrder`.
- * - `REOPEN`: `reopenOrder`. Needs `UpdateOrder`.
+ * - `MARK_COMPLETED`: `orders.markCompleted`. Needs `UpdateOrder`.
+ * - `REOPEN`: `orders.reopen`. Needs `UpdateOrder`.
+ * - `SET_PAYMENT_NOT_REQUIRED`: `orders.setPaymentNotRequired`, in the direction it would go
+ *   next: lifting the waiver while the order carries one (`lifecycle.payment` then reads
+ *   `not_required`), waiving it otherwise. A cancelled order changes neither way (`CANCELLED`);
+ *   an order whose payment reads `not_required` without a waiver (a total of 0) has nothing to
+ *   waive or lift (`STATE`); a waiver waits while an invoice still bills the order
+ *   (`CREDIT_NOTE_REQUIRED`). The write refuses the `CANCELLED` and `CREDIT_NOTE_REQUIRED`
+ *   cases, `ORDER_PAYMENT_WAIVER_REFUSED`; it takes a waiver on a zero-total order, which this
+ *   action does not offer. Needs `UpdateOrder`.
+ * - `SET_FULFILLMENT_HOLD`: `orders.setFulfillmentHold`, in the direction it would go next: a
+ *   release while `lifecycle.fulfillment` is `on_hold` (any order but a live cart), a new hold
+ *   only on an open order (`STATE` otherwise). Needs `UpdateOrder`.
+ * - `SET_GOODWILL_ROUNDING`: `orders.setGoodwillRounding`, either way (apply or clear). Closed
+ *   once the order's total no longer moves: an invoice bills it (`INVOICE_LOCKED`), it is
+ *   completed or cancelled (`COMPLETED`, `CANCELLED`), or it is settled or invoiced in the
+ *   store's ERP (`ERP_LOCKED`); the write then refuses `GOODWILL_ROUNDING_LOCKED`. Whether
+ *   there is anything to round (one VAT rate, a total that is not whole) is not answered here:
+ *   applying to such an order is refused `GOODWILL_ROUNDING_NOT_APPLICABLE`. Needs
+ *   `UpdateOrder`. Whether APPLYING one is open is `APPLY_GOODWILL_ROUNDING`.
+ * - `APPLY_GOODWILL_ROUNDING`: `orders.setGoodwillRounding` with `apply: true`. The same lock as
+ *   `SET_GOODWILL_ROUNDING` first, then `LEAVES_MONEY_OVER`: the order is paid, and its payments
+ *   would hold more than the rounded total; the write then refuses
+ *   `GOODWILL_ROUNDING_LEAVES_MONEY_OVER`, because the rounding refunds nothing. Clearing a
+ *   rounding stays `SET_GOODWILL_ROUNDING` alone. Needs `UpdateOrder`.
+ * - `SET_BILLING_FIELDS`: a change of `customFields.removeTax`, `paymentTermsDays` or
+ *   `paymentConditionCode`, the order's fields that decide what it BILLS, through the engine's
+ *   `setOrderCustomFields` or `setOrderRemoveTax`. Closed while a live invoice bills the order
+ *   (`INVOICE_LOCKED`): its standard invoice not voided, or an accounts-receivable invoice
+ *   neither voided nor superseded. The write then refuses `ORDER_INVOICE_LOCKED` (422), with
+ *   the field in `details[].field` (a pointer into the arguments) and a sentence naming the
+ *   invoice and its ledger in `details[].message`; what the order bills is changed through that
+ *   invoice's correction (`documents.commitCorrection`). A value equal to the stored one is
+ *   never refused, and notes and the order's reference (`orders.setPurchaseOrderNumber`) are
+ *   not part of it. It answers those two writes only, and they store the value without
+ *   recalculating the order. Applying it to the order's amounts (the order edit:
+ *   `orders.planEdit`, `orders.commitEdit`), and changing a line's `unitPriceOverride` or
+ *   `unitPriceImported`, which this lock refuses too, are also closed while `MODIFY` answers
+ *   `INVOICE_LOCKED`, and that outlives the void of a retail invoice. The void opens the payment
+ *   terms again, not `removeTax`: `SET_PRICING_FIELDS` answers that. Needs `UpdateOrder`.
+ * - `SET_PRICING_FIELDS`: a change of `customFields.removeTax`, or of a line's
+ *   `unitPriceOverride` or `unitPriceImported`, the fields that decide the order's AMOUNTS, at
+ *   the engine's custom-field writes (`setOrderCustomFields`, `setOrderRemoveTax`,
+ *   `modifyOrder`, the draft line writes). Closed (`INVOICE_LOCKED`) while a live invoice bills
+ *   the order, and while its content stays locked with none: after its retail invoice was
+ *   voided, and on an order the platform it was imported from invoiced. Nothing recalculates
+ *   such an order, so its tax and prices stay as invoiced. The write refuses
+ *   `ORDER_INVOICE_LOCKED` (422) with the field in `details[].field` and the reason in
+ *   `details[].message`. A value equal to the stored one is never refused; the payment terms
+ *   are not part of it. Needs `UpdateOrder`.
+ *
+ * The two toggles are answered by engines from W10-25 on, the rounding from W10-26 on, and
+ * `SET_BILLING_FIELDS` and `SET_PRICING_FIELDS` from the engines that enforce them on; an older
+ * engine leaves them out of `actions`. For the first three that reads as "not available"; an
+ * engine that does not answer `SET_BILLING_FIELDS` does not lock those fields either, and one
+ * that does not answer `SET_PRICING_FIELDS` locks them only as `SET_BILLING_FIELDS` says. `APPLY_GOODWILL_ROUNDING` is answered
+ * by the engine that refuses a rounding on a paid order; an older one leaves it out and does not
+ * refuse it, so read a missing answer as "not available" (never offer the rounding on a guess).
  * - `CORRECT_FULFILLMENT`: one of TWO writes, with different gates.
- *   - `updateFulfillmentLineQuantities` needs `UpdateOrder`, and corrects any
- *     fulfillment of the order on any store.
+ *   - `updateFulfillmentLineQuantities` (`orders.correctFulfillmentQuantities`) needs
+ *     `UpdateOrder`, and corrects any fulfillment of the order on any store. A credential
+ *     restricted to stock locations (an API token or app installation with `locationIds`)
+ *     corrects only a fulfillment that ships from one of them (`LOCATION_OUT_OF_SCOPE`
+ *     otherwise).
  *   - `correctFulfillmentQuantities` needs `UpdateFulfillment` or
  *     `UpdateOrder`, and works only on a store with the warehouse workspace
  *     (`WAREHOUSE_NOT_ENABLED` otherwise). For a caller without `UpdateOrder`
@@ -73,7 +135,8 @@ export declare const ORDER_STATUS_ACTIONS: readonly ["MODIFY", "DELETE", "RELEAS
  *     quantity (`OFFICE_ONLY`).
  *
  *   So `allowed` is true for a caller with `UpdateOrder` whenever the order is
- *   eligible. For a caller holding `UpdateFulfillment` without `UpdateOrder`
+ *   eligible, except a credential restricted to stock locations, for which it is true only
+ *   while one of THIS order's fulfillments ships from one of its locations. 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
@@ -86,7 +149,7 @@ export declare const ORDER_STATUS_ACTIONS: readonly ["MODIFY", "DELETE", "RELEAS
  */
 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"];
+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", "CREDIT_NOTE_REQUIRED", "HOLDS_MONEY", "ERP_LOCKED", "LEAVES_MONEY_OVER", "PERMISSION"];
 /**
  * - `INVOICE_LOCKED`, `COMPLETED`, `CANCELLED`: the edit block.
  * - `STATE`: the order's state does not allow it.
@@ -104,6 +167,31 @@ export declare const ORDER_STATUS_REASON_CODES: readonly ["INVOICE_LOCKED", "COM
  *   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.
+ * - `CREDIT_NOTE_REQUIRED` (`CANCEL` and `SET_PAYMENT_NOT_REQUIRED`): an invoice
+ *   still bills the order, paid or not. For `SET_PAYMENT_NOT_REQUIRED`, correct
+ *   the invoice first. For `CANCEL`, cancelling (whole or by lines) would leave
+ *   the invoice standing. Do what {@link OrderStatusView.cancelCreditNote}'s `remedy`
+ *   says first, then cancel: `CORRECT_INVOICE`, correct the invoice it names
+ *   (`documents.commitCorrection` on its ledger: credit it in full, with a
+ *   refund on a retail invoice); `REFUND_PAYMENT`, refund the order's settled
+ *   payment (`payments.refund`), whose AR credit note corrects the invoice,
+ *   and do NOT correct it as well (that credits the customer twice). Both cancel
+ *   doors (`cancelOrder` and `orders.cancelWithMoney`) refuse
+ *   `ORDER_CANCEL_CREDIT_NOTE_CONFLICT` (409) meanwhile. Named before
+ *   `HOLDS_MONEY`.
+ * - `HOLDS_MONEY`: `CANCEL` only. The order has been placed or parked and
+ *   still holds money, which a plain cancel would leave on it (the Admin
+ *   `cancelOrder` refuses it `ORDER_HOLDS_MONEY`). Cancel it with
+ *   `orders.cancelWithMoney`, or give its money back first: refund settled
+ *   payments, cancel card holds (a hold released at the payment provider
+ *   first where its payment method cannot). The value of spent gift cards
+ *   sold on it is never given back: only `orders.cancelWithMoney`'s
+ *   `retain` keeps it.
+ * - `ERP_LOCKED`: `SET_GOODWILL_ROUNDING` and `APPLY_GOODWILL_ROUNDING` only. The order is
+ *   settled or invoiced in the store's ERP, which holds its total: correct it there.
+ * - `LEAVES_MONEY_OVER`: `APPLY_GOODWILL_ROUNDING` only. The order is paid: rounding its total
+ *   down would leave the customer's money over the rounded total, which nothing pays back.
+ *   Refund the customer instead.
  * - `PERMISSION`: the order allows it and this caller may not. The only
  *   reason about the caller.
  */
@@ -147,13 +235,18 @@ export interface OrderStatusView {
         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).
+         * Set only when the reason is `INVOICE`: the live standard retail invoice,
+         * else the live accounts-receivable invoice billing the order, else a voided
+         * standard retail one (voiding a retail invoice does not unlock the order;
+         * an AR invoice locks only while it is live, so it is never voided here).
+         * `ledger` is `RETAIL` or `AR`: the ledger to correct it on
+         * (`documents.planCorrection`).
          */
         lockingInvoice: {
             id: string;
             number: string;
             voided: boolean;
+            ledger: 'RETAIL' | 'AR' | (string & {});
         } | null;
     };
     /** Null when the order's content may change; the message is the one every edit is refused with. */
@@ -192,6 +285,12 @@ export interface OrderStatusView {
      * fulfillment provider, and the store blocks shipping it again.
      */
     sourceFulfilled: boolean;
+    /**
+     * Why `sourceFulfilled` is true, in words for staff (the source platform and its order
+     * number), the same sentence the warehouse demand carries; null when it is false. Show it as
+     * sent rather than composing one.
+     */
+    sourceFulfilledReason: string | null;
     /** Set while the order is parked. */
     park: {
         reason: string | null;
@@ -207,6 +306,13 @@ export interface OrderStatusView {
     } | null;
     /** Empty when the order runs on every provider the store assigned. */
     providerFallbacks: OrderStatusProviderFallback[];
+    /**
+     * Set while a cancel (whole or by lines) waits for a credit note (`CANCEL` answers
+     * `CREDIT_NOTE_REQUIRED`, unless a more fundamental reason comes first).
+     * This SDK's document selects it, so against an engine older than the field
+     * `status` fails validation: deploy the engine first.
+     */
+    cancelCreditNote: OrderStatusCancelCreditNote | null;
     /**
      * The states a change-status menu lists, in the engine's order: without
      * `Cancelled` and `Modifying` (their own actions), without the cart phase,
@@ -216,7 +322,41 @@ export interface OrderStatusView {
     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";
+/**
+ * Why a cancel (whole or by lines) waits for a credit note: an invoice still
+ * bills the order, paid or not (cancelling would leave the invoice
+ * standing for revenue the order no longer has).
+ */
+export interface OrderStatusCancelCreditNote {
+    /** The `InvoiceCorrectionLedger` to correct the invoice on: `RETAIL` or `AR`. */
+    ledger: 'RETAIL' | 'AR' | (string & {});
+    /**
+     * What to do first. `CORRECT_INVOICE`: correct this invoice (credited in
+     * full; a `RETAIL` correction refunds along). `REFUND_PAYMENT`: refund the
+     * order's settled payment first (`payments.refund`): on an AR-invoiced
+     * order the refund issues the AR credit note that corrects the invoice, and
+     * correcting the invoice as well would credit the customer twice.
+     */
+    remedy: 'CORRECT_INVOICE' | 'REFUND_PAYMENT' | (string & {});
+    invoiceId: string;
+    invoiceNumber: string;
+    /**
+     * What the invoice still bills the order for, in minor units of
+     * `currencyCode`: its total (on `AR`, the order's share) less its credit
+     * notes.
+     */
+    uncredited: number;
+    /**
+     * What the order still holds, in minor units of `currencyCode`: its settled
+     * payments less what went back, or the receipts on its live
+     * accounts-receivable invoices, whichever is larger (a collected direct
+     * debit records the same money on both).
+     */
+    held: number;
+    /** The order's currency. */
+    currencyCode: string;
+}
+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          ledger\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      sourceFulfilledReason\n      park {\n        reason\n      }\n      hold {\n        forReview\n        byApp\n      }\n      providerFallbacks {\n        kind\n        installationId\n        reason\n        since\n      }\n      cancelCreditNote {\n        ledger\n        remedy\n        invoiceId\n        invoiceNumber\n        uncredited\n        held\n        currencyCode\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.
@@ -227,8 +367,14 @@ export interface OrderStatusModule {
      * 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.
+     * An order a live accounts-receivable invoice bills is invoice-locked like a
+     * retail-invoiced one (`INVOICE_LOCKED`, `lock.lockingInvoice.ledger: 'AR'`).
+     *
+     * Needs an engine that serves `orderStatus` with `cancelCreditNote`,
+     * `lock.lockingInvoice.ledger` and `sourceFulfilledReason`; against an older
+     * one this call fails validation and nothing else does.
+     *
+     * @effect read
      */
     status(orderId: string, options?: Call): Promise<OrderStatusView>;
 }

package/dist/orders/status.js

@@ -14,6 +14,12 @@ export const ORDER_STATUS_ACTIONS = [
     'TRANSITION',
     'MARK_COMPLETED',
     'REOPEN',
+    'SET_PAYMENT_NOT_REQUIRED',
+    'SET_FULFILLMENT_HOLD',
+    'SET_GOODWILL_ROUNDING',
+    'SET_BILLING_FIELDS',
+    'APPLY_GOODWILL_ROUNDING',
+    'SET_PRICING_FIELDS',
 ];
 /** Why an action is not allowed, in the order the engine lists them. */
 export const ORDER_STATUS_REASON_CODES = [
@@ -27,6 +33,10 @@ export const ORDER_STATUS_REASON_CODES = [
     'SHOPPER_CART',
     'UNITS_SHIPPED',
     'ACTIVE_FULFILLMENT',
+    'CREDIT_NOTE_REQUIRED',
+    'HOLDS_MONEY',
+    'ERP_LOCKED',
+    'LEAVES_MONEY_OVER',
     'PERMISSION',
 ];
 export const ORDER_STATUS_QUERY = /* GraphQL */ `
@@ -47,6 +57,7 @@ export const ORDER_STATUS_QUERY = /* GraphQL */ `
           id
           number
           voided
+          ledger
         }
       }
       editBlock {
@@ -63,6 +74,7 @@ export const ORDER_STATUS_QUERY = /* GraphQL */ `
         code
       }
       sourceFulfilled
+      sourceFulfilledReason
       park {
         reason
       }
@@ -76,6 +88,15 @@ export const ORDER_STATUS_QUERY = /* GraphQL */ `
         reason
         since
       }
+      cancelCreditNote {
+        ledger
+        remedy
+        invoiceId
+        invoiceNumber
+        uncredited
+        held
+        currencyCode
+      }
       nextStates
       actions {
         action