@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/orders/list.d.ts

@@ -0,0 +1,222 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * One order as a list shows it (`admin.orders.list`, `admin.customers.orders`): the totals, the
+ * status dimensions, who it is for, and the three company sources a display name reads
+ * (`billingAddress.company`, `shippingAddress.company`, the customer's address book).
+ *
+ * Money is an integer in minor units of the order's `currencyCode`.
+ */
+export interface OrderSummary {
+    id: string;
+    code: string;
+    state: string;
+    total: number;
+    totalWithTax: number;
+    currencyCode: string;
+    /** ISO-8601; null for an order not placed yet (a cart, a draft). */
+    orderPlacedAt: string | null;
+    customer: {
+        id: string;
+        firstName: string;
+        lastName: string;
+        emailAddress: string;
+        addresses: Array<{
+            company: string | null;
+            defaultBillingAddress: boolean | null;
+            defaultShippingAddress: boolean | null;
+        }> | null;
+    } | null;
+    billingAddress: {
+        company: string | null;
+    } | null;
+    shippingAddress: {
+        company: string | null;
+    } | null;
+    lines: Array<{
+        quantity: number;
+    }>;
+    payments: Array<{
+        id: string;
+        state: string;
+    }> | null;
+    customFields: {
+        externalOrderId: string | null;
+        externalPlatform: string | null;
+        isGift: boolean | null;
+        /** The status dimensions; null until the engine has set them on an older order. */
+        paymentStatus: string | null;
+        fulfillmentStatus: string | null;
+        returnStatus: string | null;
+        lifecycleStatus: string | null;
+        statusOverrides: {
+            fulfillmentHoldReason: string | null;
+        } | null;
+    } | null;
+    /**
+     * Set when the caller's customer-data level blanked part of the row (an app installation below
+     * `customerData: full`): read an empty name or company as "not granted", never as "none".
+     */
+    redacted?: true;
+}
+/**
+ * Which orders a list holds. Every key narrows it; several keys are combined with AND. An empty
+ * list (`state: []`) matches nothing.
+ */
+export interface OrderListFilter {
+    ids?: readonly string[];
+    /** Any of these engine states (`PaymentSettled`, `Draft`, …). */
+    state?: readonly string[];
+    /**
+     * The order code. `startsWith` and `contains` ignore case; `contains` treats `%` and `_` as
+     * wildcards.
+     */
+    code?: {
+        eq?: string;
+        contains?: string;
+        startsWith?: string;
+    };
+    /**
+     * When the order was placed. `isNull: true` keeps the orders never placed (carts, drafts),
+     * `false` the placed ones. `before`/`after` are ISO-8601 instants WITH an offset or `Z`, both
+     * exclusive; an order never placed matches neither.
+     */
+    orderPlacedAt?: {
+        isNull?: boolean;
+        before?: string;
+        after?: string;
+    };
+    /** True for a cart its shopper still has open; a draft, placed or cancelled order is not. */
+    active?: boolean;
+    currencyCode?: string;
+    /**
+     * The platform an imported order came from (`woocommerce`, …); `null` keeps only the orders
+     * that were not imported.
+     */
+    externalPlatform?: string | null;
+    /** Any of these payment dimensions (`paid`, `partially_paid`, …). */
+    paymentStatus?: readonly string[];
+    /** Any of these lifecycles (`open`, `completed`, …). */
+    lifecycleStatus?: readonly string[];
+    /** Part of the customer's last name, ignoring case. */
+    customerLastName?: string;
+}
+/** The fields an order list sorts on. */
+export type OrderListSortField = 'orderPlacedAt' | 'createdAt' | 'updatedAt' | 'code' | 'state' | 'total' | 'totalWithTax' | 'customerLastName';
+export declare const ORDER_LIST_SORT_FIELDS: readonly OrderListSortField[];
+export interface OrderListSort {
+    field: OrderListSortField;
+    direction: 'ASC' | 'DESC';
+}
+export interface OrderListOptions extends Call {
+    filter?: OrderListFilter;
+    sort?: OrderListSort;
+    /** Rows to skip, 0 when omitted. */
+    skip?: number;
+    /** Rows per page, 1 to {@link MAX_ORDER_LIST_TAKE}; 25 when omitted. */
+    take?: number;
+}
+/** The engine's `adminListQueryLimit`: a larger page is refused. */
+export declare const MAX_ORDER_LIST_TAKE = 1000;
+export declare const ORDER_SUMMARY_FIELDS = "\n  id\n  code\n  state\n  total\n  totalWithTax\n  currencyCode\n  orderPlacedAt\n  customer {\n    id\n    firstName\n    lastName\n    emailAddress\n    addresses {\n      company\n      defaultBillingAddress\n      defaultShippingAddress\n    }\n  }\n  billingAddress {\n    company\n  }\n  shippingAddress {\n    company\n  }\n  lines {\n    quantity\n  }\n  payments {\n    id\n    state\n  }\n  customFields {\n    externalOrderId\n    externalPlatform\n    isGift\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n    lifecycleStatus\n    statusOverrides {\n      fulfillmentHoldReason\n    }\n  }\n";
+export declare const ORDERS_LIST_QUERY = "\n  query OrdersList($options: OrderListOptions) {\n    orders(options: $options) {\n      items {\n        \n  id\n  code\n  state\n  total\n  totalWithTax\n  currencyCode\n  orderPlacedAt\n  customer {\n    id\n    firstName\n    lastName\n    emailAddress\n    addresses {\n      company\n      defaultBillingAddress\n      defaultShippingAddress\n    }\n  }\n  billingAddress {\n    company\n  }\n  shippingAddress {\n    company\n  }\n  lines {\n    quantity\n  }\n  payments {\n    id\n    state\n  }\n  customFields {\n    externalOrderId\n    externalPlatform\n    isGift\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n    lifecycleStatus\n    statusOverrides {\n      fulfillmentHoldReason\n    }\n  }\n\n      }\n      totalItems\n    }\n  }\n";
+export declare const ORDERS_COUNT_QUERY = "\n  query OrdersCount($options: OrderListOptions) {\n    orders(options: $options) {\n      totalItems\n    }\n  }\n";
+export declare const CUSTOMER_ORDERS_QUERY = "\n  query CustomerOrders($id: ID!, $options: OrderListOptions) {\n    customer(id: $id) {\n      id\n      orders(options: $options) {\n        items {\n          \n  id\n  code\n  state\n  total\n  totalWithTax\n  currencyCode\n  orderPlacedAt\n  customer {\n    id\n    firstName\n    lastName\n    emailAddress\n    addresses {\n      company\n      defaultBillingAddress\n      defaultShippingAddress\n    }\n  }\n  billingAddress {\n    company\n  }\n  shippingAddress {\n    company\n  }\n  lines {\n    quantity\n  }\n  payments {\n    id\n    state\n  }\n  customFields {\n    externalOrderId\n    externalPlatform\n    isGift\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n    lifecycleStatus\n    statusOverrides {\n      fulfillmentHoldReason\n    }\n  }\n\n        }\n        totalItems\n      }\n    }\n  }\n";
+/** The Admin API's `OrderFilterParameter` for a typed filter; unknown keys are refused. */
+export declare function toOrderFilterParameter(filter: OrderListFilter | undefined): Record<string, unknown>;
+export interface OrderListModule {
+    /**
+     * One page of the store's orders, with `total` the exact count of every order the filter
+     * matches. Needs `ReadOrder`.
+     *
+     * - **Carts are orders too.** A cart a shopper never checked out, and a draft staff never placed,
+     *   are listed unless the filter leaves them out (`orderPlacedAt: { isNull: false }`).
+     * - **Sorting by `orderPlacedAt` descending puts the never-placed rows FIRST** (the database
+     *   sorts an empty date above every date). To show the newest placed order first, list the
+     *   placed orders, then continue with `orderPlacedAt: { isNull: true }` sorted by `createdAt`.
+     * - `page.next()` asks for the following page with the same filter and sort; `skip` starts
+     *   somewhere else.
+     *
+     * Refused before anything is asked: `INVALID_ORDER_LIST_OPTIONS` (`ValidationError`, 400) for a
+     * filter key or operator it does not list, a date without an offset, a sort field it does not
+     * list, or `take`/`skip` out of range.
+     *
+     * @effect read
+     */
+    list(options?: OrderListOptions): Promise<Page<OrderSummary>>;
+    /**
+     * How many of the store's orders the filter matches, without reading any. Carts count unless
+     * the filter leaves them out. Needs `ReadOrder`. Refused like {@link list}.
+     *
+     * @effect read
+     */
+    count(filter?: OrderListFilter, options?: Call): Promise<number>;
+}
+export declare function createOrderListModule(transport: Transport): OrderListModule;
+/**
+ * One customer's orders, as `customers.orders` reads them: the same rows, filter, sort and paging
+ * as `orders.list`, or `null` when the store holds no customer with that id.
+ */
+export declare function listCustomerOrders(transport: Transport, customerId: string, options: OrderListOptions | undefined): Promise<Page<OrderSummary> | null>;
+/** The most orders `customers.recentOrders` answers. */
+export declare const MAX_RECENT_ORDERS = 20;
+/**
+ * One line of a customer's earlier order: what was bought, and how many. The members are named
+ * as on every other order line of this SDK (`orders.get`, `orders.drafts`).
+ */
+export interface RecentOrderLine {
+    id: string;
+    /** 0 for a line that was cancelled on the order. */
+    quantity: number;
+    /**
+     * Whether the line is priced gross. `customFields.unitPriceOverride` is stated in this basis,
+     * which follows the customer's tax zone, not the store's setting: a store that prices gross
+     * still holds net lines for a customer in a tax-exclusive country.
+     */
+    listPriceIncludesTax: boolean;
+    /**
+     * The variant as it is NOW (its name and SKU may have changed since the order). A line an
+     * external system priced sits on the platform's hidden carrier variant: read it through
+     * `catalog.variants.find({ ids })`, which leaves such a variant out, before offering it.
+     */
+    productVariant: {
+        id: string;
+        name: string;
+        sku: string;
+        product: {
+            id: string;
+            name: string;
+        };
+    };
+    customFields: {
+        /**
+         * The unit price the line states in place of the catalogue's, in minor units of the
+         * order's currency and in the line's basis (`listPriceIncludesTax`); null for a line the
+         * catalogue priced.
+         */
+        unitPriceOverride: number | null;
+        /** True when that price arrived with the line (an import, a quote, a till price). */
+        unitPriceImported: boolean | null;
+    } | null;
+}
+/** A placed order of a customer, with its lines. */
+export interface RecentOrder {
+    id: string;
+    code: string;
+    /** ISO-8601. */
+    orderPlacedAt: string;
+    /** Minor units of `currencyCode`. */
+    totalWithTax: number;
+    currencyCode: string;
+    lines: RecentOrderLine[];
+}
+export interface RecentOrdersOptions extends Call {
+    /** How many orders, 1 to {@link MAX_RECENT_ORDERS}; 5 when omitted. */
+    take?: number;
+}
+export declare const CUSTOMER_RECENT_ORDERS_QUERY = "\n  query CustomerRecentOrders($id: ID!, $options: OrderListOptions) {\n    customer(id: $id) {\n      id\n      orders(options: $options) {\n        items {\n          id\n          code\n          orderPlacedAt\n          totalWithTax\n          currencyCode\n          lines {\n            id\n            quantity\n            listPriceIncludesTax\n            productVariant {\n              id\n              name\n              sku\n              product {\n                id\n                name\n              }\n            }\n            customFields {\n              unitPriceOverride\n              unitPriceImported\n            }\n          }\n        }\n        totalItems\n      }\n    }\n  }\n";
+/**
+ * A customer's last placed orders, newest first, each with its lines, as `customers.recentOrders`
+ * reads them; `null` when the store holds no customer with that id.
+ */
+export declare function listCustomerRecentOrders(transport: Transport, customerId: string, options: RecentOrdersOptions | undefined): Promise<RecentOrder[] | null>;

package/dist/orders/list.js

@@ -0,0 +1,377 @@
+import { pageFromVendureList, readOffsetCursor, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
+import { redactionWatcher } from '../customer-data-redaction.js';
+export const ORDER_LIST_SORT_FIELDS = [
+    'orderPlacedAt',
+    'createdAt',
+    'updatedAt',
+    'code',
+    'state',
+    'total',
+    'totalWithTax',
+    'customerLastName',
+];
+/** The engine's `adminListQueryLimit`: a larger page is refused. */
+export const MAX_ORDER_LIST_TAKE = 1000;
+const DEFAULT_TAKE = 25;
+export const ORDER_SUMMARY_FIELDS = /* GraphQL */ `
+  id
+  code
+  state
+  total
+  totalWithTax
+  currencyCode
+  orderPlacedAt
+  customer {
+    id
+    firstName
+    lastName
+    emailAddress
+    addresses {
+      company
+      defaultBillingAddress
+      defaultShippingAddress
+    }
+  }
+  billingAddress {
+    company
+  }
+  shippingAddress {
+    company
+  }
+  lines {
+    quantity
+  }
+  payments {
+    id
+    state
+  }
+  customFields {
+    externalOrderId
+    externalPlatform
+    isGift
+    paymentStatus
+    fulfillmentStatus
+    returnStatus
+    lifecycleStatus
+    statusOverrides {
+      fulfillmentHoldReason
+    }
+  }
+`;
+export const ORDERS_LIST_QUERY = /* GraphQL */ `
+  query OrdersList($options: OrderListOptions) {
+    orders(options: $options) {
+      items {
+        ${ORDER_SUMMARY_FIELDS}
+      }
+      totalItems
+    }
+  }
+`;
+export const ORDERS_COUNT_QUERY = /* GraphQL */ `
+  query OrdersCount($options: OrderListOptions) {
+    orders(options: $options) {
+      totalItems
+    }
+  }
+`;
+export const CUSTOMER_ORDERS_QUERY = /* GraphQL */ `
+  query CustomerOrders($id: ID!, $options: OrderListOptions) {
+    customer(id: $id) {
+      id
+      orders(options: $options) {
+        items {
+          ${ORDER_SUMMARY_FIELDS}
+        }
+        totalItems
+      }
+    }
+  }
+`;
+function invalid(message) {
+    return new ValidationError({
+        code: 'INVALID_ORDER_LIST_OPTIONS',
+        message,
+        status: 400,
+        service: 'vendure',
+    });
+}
+function stringList(value, path) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw invalid(`${path} must be a list of strings.`);
+    }
+    return [...value];
+}
+function text(value, path) {
+    if (typeof value !== 'string')
+        throw invalid(`${path} must be a string.`);
+    return value;
+}
+/**
+ * An instant the engine compares without guessing a zone: a string with no offset would be read
+ * in the database server's zone, so a range would shift by hours with the server.
+ */
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/;
+function instant(value, path) {
+    if (typeof value !== 'string' || !INSTANT.test(value) || Number.isNaN(Date.parse(value))) {
+        throw invalid(`${path} must be an ISO-8601 instant with an offset or Z.`);
+    }
+    return value;
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** The Admin API's `OrderFilterParameter` for a typed filter; unknown keys are refused. */
+export function toOrderFilterParameter(filter) {
+    if (filter === undefined)
+        return {};
+    if (typeof filter !== 'object' || filter === null || Array.isArray(filter)) {
+        throw invalid('filter must be an object.');
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(filter)) {
+        if (value === undefined)
+            continue;
+        switch (key) {
+            case 'ids':
+                out.id = { in: stringList(value, 'filter.ids') };
+                break;
+            case 'state':
+            case 'paymentStatus':
+            case 'lifecycleStatus':
+                out[key] = { in: stringList(value, `filter.${key}`) };
+                break;
+            case 'code': {
+                const code = value;
+                if (typeof code !== 'object' || code === null)
+                    throw invalid('filter.code must be an object.');
+                const operators = {};
+                for (const [operator, operand] of Object.entries(code)) {
+                    if (operand === undefined)
+                        continue;
+                    const path = `filter.code.${operator}`;
+                    if (operator === 'eq' || operator === 'contains')
+                        operators[operator] = text(operand, path);
+                    else if (operator === 'startsWith')
+                        operators.regex = `^${escapeRegex(text(operand, path))}`;
+                    else
+                        throw invalid(`${path} is not a code filter; use eq, contains or startsWith.`);
+                }
+                out.code = operators;
+                break;
+            }
+            case 'orderPlacedAt': {
+                const placed = value;
+                if (typeof placed !== 'object' || placed === null) {
+                    throw invalid('filter.orderPlacedAt must be an object.');
+                }
+                const operators = {};
+                for (const [operator, operand] of Object.entries(placed)) {
+                    if (operand === undefined)
+                        continue;
+                    const path = `filter.orderPlacedAt.${operator}`;
+                    if (operator === 'isNull') {
+                        if (typeof operand !== 'boolean')
+                            throw invalid(`${path} must be a boolean.`);
+                        operators.isNull = operand;
+                    }
+                    else if (operator === 'before' || operator === 'after') {
+                        operators[operator] = instant(operand, path);
+                    }
+                    else {
+                        throw invalid(`${path} is not a date filter; use isNull, before or after.`);
+                    }
+                }
+                out.orderPlacedAt = operators;
+                break;
+            }
+            case 'active':
+                if (typeof value !== 'boolean')
+                    throw invalid('filter.active must be a boolean.');
+                out.active = { eq: value };
+                break;
+            case 'currencyCode':
+                out.currencyCode = { eq: text(value, 'filter.currencyCode') };
+                break;
+            case 'externalPlatform':
+                out.externalPlatform =
+                    value === null ? { isNull: true } : { eq: text(value, 'filter.externalPlatform') };
+                break;
+            case 'customerLastName':
+                out.customerLastName = { contains: text(value, 'filter.customerLastName') };
+                break;
+            default:
+                throw invalid(`filter.${key} is not an order list filter.`);
+        }
+    }
+    return out;
+}
+function toOrderSort(sort) {
+    if (sort === undefined)
+        return undefined;
+    if (typeof sort !== 'object' ||
+        sort === null ||
+        !ORDER_LIST_SORT_FIELDS.includes(sort.field) ||
+        (sort.direction !== 'ASC' && sort.direction !== 'DESC')) {
+        throw invalid(`sort must be { field: ${ORDER_LIST_SORT_FIELDS.join(' | ')}, direction: ASC | DESC }.`);
+    }
+    return { [sort.field]: sort.direction };
+}
+function pageBounds(options) {
+    const take = options?.take ?? DEFAULT_TAKE;
+    const skip = options?.skip ?? 0;
+    if (!Number.isInteger(take) || take < 1 || take > MAX_ORDER_LIST_TAKE) {
+        throw invalid(`take must be a whole number from 1 to ${String(MAX_ORDER_LIST_TAKE)}.`);
+    }
+    if (!Number.isInteger(skip) || skip < 0)
+        throw invalid('skip must be a whole number of 0 or more.');
+    return { skip, take };
+}
+/**
+ * Pages through one order list. `read` answers the list (or `null` when its owner is gone); each
+ * following page re-sends the same filter, sort and per-call options, so a page cannot walk
+ * another store's orders.
+ */
+async function listOrders(read, options) {
+    const { skip, take } = pageBounds(options);
+    const filter = toOrderFilterParameter(options?.filter);
+    const sort = toOrderSort(options?.sort);
+    const fetchPage = async (pageSkip) => {
+        const redaction = redactionWatcher();
+        const list = await read({
+            options: {
+                skip: pageSkip,
+                take,
+                ...(Object.keys(filter).length > 0 ? { filter, filterOperator: 'AND' } : {}),
+                ...(sort ? { sort } : {}),
+            },
+        }, redaction.onExtensions);
+        if (list === null)
+            return null;
+        return pageFromVendureList({ items: list.items.map((item) => redaction.mark(item)), totalItems: list.totalItems }, pageSkip, take, async (cursor) => {
+            const next = await fetchPage(readOffsetCursor(cursor));
+            if (next === null) {
+                throw new UpstreamError({
+                    code: 'UNEXPECTED_RESPONSE',
+                    message: 'The customer was gone by the next page of their orders.',
+                    status: 502,
+                    service: 'vendure',
+                });
+            }
+            return next;
+        });
+    };
+    return fetchPage(skip);
+}
+export function createOrderListModule(transport) {
+    return {
+        async list(options) {
+            const page = await listOrders(async (variables, onExtensions) => {
+                const data = await transport.graphql({ api: 'admin', query: ORDERS_LIST_QUERY, variables, onExtensions }, options);
+                return data.orders;
+            }, options);
+            // `read` above never answers null: the store's own list always exists.
+            return page;
+        },
+        async count(filter, options) {
+            const parameter = toOrderFilterParameter(filter);
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ORDERS_COUNT_QUERY,
+                variables: {
+                    options: {
+                        // Never 0: Vendure passes it through and TypeORM then sends no LIMIT, so a
+                        // "count" would load every matching order. One row costs nothing.
+                        take: 1,
+                        ...(Object.keys(parameter).length > 0
+                            ? { filter: parameter, filterOperator: 'AND' }
+                            : {}),
+                    },
+                },
+            }, options);
+            return data.orders.totalItems;
+        },
+    };
+}
+/**
+ * One customer's orders, as `customers.orders` reads them: the same rows, filter, sort and paging
+ * as `orders.list`, or `null` when the store holds no customer with that id.
+ */
+export async function listCustomerOrders(transport, customerId, options) {
+    return listOrders(async (variables, onExtensions) => {
+        const data = await transport.graphql({
+            api: 'admin',
+            query: CUSTOMER_ORDERS_QUERY,
+            variables: { id: customerId, ...variables },
+            onExtensions,
+        }, options);
+        return data.customer?.orders ?? null;
+    }, options);
+}
+/** The most orders `customers.recentOrders` answers. */
+export const MAX_RECENT_ORDERS = 20;
+const DEFAULT_RECENT_ORDERS = 5;
+export const CUSTOMER_RECENT_ORDERS_QUERY = /* GraphQL */ `
+  query CustomerRecentOrders($id: ID!, $options: OrderListOptions) {
+    customer(id: $id) {
+      id
+      orders(options: $options) {
+        items {
+          id
+          code
+          orderPlacedAt
+          totalWithTax
+          currencyCode
+          lines {
+            id
+            quantity
+            listPriceIncludesTax
+            productVariant {
+              id
+              name
+              sku
+              product {
+                id
+                name
+              }
+            }
+            customFields {
+              unitPriceOverride
+              unitPriceImported
+            }
+          }
+        }
+        totalItems
+      }
+    }
+  }
+`;
+/**
+ * A customer's last placed orders, newest first, each with its lines, as `customers.recentOrders`
+ * reads them; `null` when the store holds no customer with that id.
+ */
+export async function listCustomerRecentOrders(transport, customerId, options) {
+    const { take = DEFAULT_RECENT_ORDERS, ...call } = options ?? {};
+    if (!Number.isInteger(take) || take < 1 || take > MAX_RECENT_ORDERS) {
+        throw invalid(`take must be a whole number from 1 to ${String(MAX_RECENT_ORDERS)}.`);
+    }
+    const data = await transport.graphql({
+        api: 'admin',
+        query: CUSTOMER_RECENT_ORDERS_QUERY,
+        variables: {
+            id: customerId,
+            options: {
+                take,
+                // Placed orders only: sorted on its own, `orderPlacedAt` descending lists the carts
+                // and drafts (no date) first.
+                filter: { orderPlacedAt: { isNull: false } },
+                // ONE key, on purpose. The engine applies the keys of a sort in the order its schema
+                // declares them, not the order they are sent in, and `id` is declared before
+                // `orderPlacedAt`: an id "tie-breaker" here sorted the orders by id (found live).
+                sort: { orderPlacedAt: 'DESC' },
+            },
+        },
+    }, call);
+    // The document selects exactly the members of `RecentOrder`: the answer is the wire's.
+    return data.customer ? data.customer.orders.items : null;
+}

package/dist/orders/manual-pricing.d.ts

@@ -161,6 +161,11 @@ export interface OrderManualPricingModule {
      * neither `unitPriceOverride` nor `priceOverrideReason` (it asks for nothing); a negative price;
      * `unitPriceOverride: null` on a line an external system priced (`orders.createOrRecover`
      * external lines), which has no catalogue price to fall back to: state the price instead.
+     *
+     * `ORDER_LINE_VARIANT_UNPRICED` (`BusinessRuleError`, 422; absent from an engine released before
+     * 2026-10-10): `unitPriceOverride: null` on a line that states a manual price while its variant
+     * has no price in the store, which would leave the line nothing to charge. Nothing is written:
+     * state the price instead, or set a price for the variant in the store first.
      */
     setLinePrices(orderId: string, input: SetLinePricesInput, options?: Call): Promise<OrderDiscounts>;
     /**

package/dist/orders/order-entry.d.ts

@@ -13,19 +13,27 @@ export type ExternalLinePriceBasis = 'net' | 'gross';
 /**
  * What is going to happen to the goods.
  *
- * A fact the vertical STATES about the order rather than an instruction
- * commerce acts on in this release: nothing here creates a fulfilment or picks
- * a shipping method. It is recorded as the order's `platform.fulfilment`
- * metafield so a document, a WMS push or a later fulfilment flow can read back
- * what the caller actually asked for.
+ * Commerce ACTS on it. Nothing here creates a fulfilment or picks a shipping
+ * method, but the value decides whether the order needs a shipping method to be
+ * placed and whether a fulfilment of it owes a delivery charge. It is recorded
+ * as the order's `platform.fulfilment` metafield (only the platform writes it),
+ * so a document, a WMS push or a merchant can also read back what you asked for.
  *
  * - `pickup` — collected at a location. Needs no shipping method and no
- *   address.
+ *   address. Handed over through an ordinary fulfilment, which adds no delivery
+ *   charge and is not held to a fulfilment profile's minimum.
  * - `ship` — shipped. The order still needs a shipping method before it can
  *   leave `Draft`, and `transitionTo: 'ArrangingPayment'` on an order that has
  *   none is refused by the platform's own placement gate, not by this call.
+ *   Delivery charges and profile minimums apply as for any delivered order.
  * - `none` — neither shipped nor collected: a service, a subscription set-up,
- *   a fee.
+ *   a fee. Needs no shipping method, owes no delivery charge and takes no
+ *   profile minimum. The order is marked as having nothing to ship, so it
+ *   completes on its own once it is paid (after the store's completion grace
+ *   period). It may not hold goods that are stock-tracked: such a catalog line
+ *   is refused `LINE_NEEDS_FULFILMENT` here, and so is placing (or modifying)
+ *   the order to carry one later. Send goods as a `pickup` order, a service as
+ *   an external line.
  */
 export type ExternalOrderFulfilment = 'pickup' | 'ship' | 'none';
 /**
@@ -478,6 +486,11 @@ export interface OrderEntryModule {
      * - `LINE_DUPLICATE_VARIANT` — two catalog lines name the same variant.
      *   `details` carries the second one's `position` and the first one's
      *   `firstPosition`. Send one line with the quantity you want.
+     * - `LINE_NEEDS_FULFILMENT` — a catalog line whose variant is stock-tracked on
+     *   an order with `fulfilment: 'none'`. Nothing ships or is handed over on
+     *   such an order, so nothing would ever sell or release that stock.
+     *   `details` carries its `position` and `variantId`. Send the order as
+     *   `pickup` (or `ship`), or the service as an external line.
      * - `EXTERNAL_LINE_PROMOTION_UNSUPPORTED` — a promotion discounted one of your
      *   externally priced lines. An order-level promotion is shared across every
      *   line of an order by the engine, so the platform refuses rather than

package/dist/orders/plan-edit.d.ts

@@ -422,7 +422,7 @@ export interface OrderEditPlan {
  * the order-edit plan, so on an older one this call alone fails validation and
  * no other order call does.
  */
-export declare const PLAN_ORDER_EDIT_QUERY = "\n  query PlanOrderEdit($orderId: ID!, $diff: OrderEditDiffInput!) {\n    planOrderEdit(orderId: $orderId, diff: $diff) {\n      orderId\n      planHash\n      orderVersion\n      steps {\n        kind\n        input\n        moneyEffect\n      }\n      refund {\n        paymentId\n        amount\n      }\n      overpayment {\n        amount\n        currencyCode\n        surchargeIds\n        refund {\n          available\n          code\n          message\n        }\n        accountCredit {\n          available\n          code\n          message\n        }\n        refundWhenChosen {\n          paymentId\n          amount\n        }\n      }\n      returnState\n      blockers {\n        code\n        message\n        details\n      }\n      notices {\n        code\n        message\n        details\n      }\n      payment {\n        collected\n        reason\n        method\n      }\n      preview {\n        currencyCode\n        subTotal\n        subTotalWithTax\n        shipping\n        shippingWithTax\n        surcharges\n        surchargesWithTax\n        total\n        totalWithTax\n        taxSummary {\n          description\n          taxRate\n          taxBase\n          taxTotal\n        }\n        totalWithTaxBefore\n      }\n    }\n  }\n";
+export declare const PLAN_ORDER_EDIT_QUERY = "\n  query PlanOrderEdit($orderId: ID!, $diff: OrderEditDiffInput!) {\n    planOrderEdit(orderId: $orderId, diff: $diff) {\n      orderId\n      planHash\n      orderVersion\n      steps {\n        kind\n        input\n        moneyEffect\n      }\n      refund {\n        paymentId\n        amount\n      }\n      overpayment {\n        amount\n        currencyCode\n        surchargeIds\n        refund {\n          available\n          code\n          message\n          book\n        }\n        accountCredit {\n          available\n          code\n          message\n          book\n        }\n        refundWhenChosen {\n          paymentId\n          amount\n        }\n      }\n      returnState\n      blockers {\n        code\n        message\n        details\n      }\n      notices {\n        code\n        message\n        details\n      }\n      payment {\n        collected\n        reason\n        method\n      }\n      preview {\n        currencyCode\n        subTotal\n        subTotalWithTax\n        shipping\n        shippingWithTax\n        surcharges\n        surchargesWithTax\n        total\n        totalWithTax\n        taxSummary {\n          description\n          taxRate\n          taxBase\n          taxTotal\n        }\n        totalWithTaxBefore\n      }\n    }\n  }\n";
 export interface OrderPlanEditModule {
     /**
      * How an edit of a placed order would be carried out, and what the order