@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/pricing/price-lists.js

@@ -0,0 +1,600 @@
+/**
+ * Price lists (headless spec §9.2 `pricing`: "price lists"; W10-14): a store's B2B price lists,
+ * their entries (what each target costs), who they are assigned to, the order rules they carry,
+ * and enabling, disabling or deleting many at once.
+ *
+ * - **Money** is integer MINOR UNITS of the store's DEFAULT currency, unless an entry's
+ *   `currencyCode` names another; an entry with no `currencyCode` applies in the default
+ *   currency only. Its basis differs per figure:
+ *   - a `fixed_price` / `fixed_amount` entry: the store's price basis (gross on a tax-inclusive
+ *     store, net on a tax-exclusive one);
+ *   - a list's order minimum (`minOrderAmount`): its own `minOrderAmountBasis`, `net` or
+ *     `gross`, and `gross` when omitted, whatever the store's basis;
+ *   - an order rule's money (a `min_order_total` threshold, a `fixed_amount` discount): the
+ *     store's price basis, as the dashboard labels it (USER DECISION N7, 2026-10-13).
+ *   Percentages are basis points (`1000` = 10 %).
+ * - **Order rules apply** (USER DECISION N1). A customer a list reaches gets the single best rule
+ *   their order meets (the most money off), as one line-level discount named "Order discount" in
+ *   the order's language. Only the most specific level of lists with rules decides (contract →
+ *   customer → group → store-wide); lists at that level are compared together. A total threshold
+ *   reads the goods at the customer's own prices before any other discount, in the store's price
+ *   basis, leaving out shipping, fees, gift cards and stated-price lines (imports, accepted
+ *   quotes, till manager prices); a quantity threshold counts the units of those same lines.
+ *   Money converts into the order's currency at the order's rate (no rate: no discount). Drafts,
+ *   storefront carts and till sales with a customer get it; quote, import and subscription
+ *   orders never do. A placed order keeps the rule SET it was placed with: an edit takes the
+ *   discount off below the threshold and gives it above it, and later rule changes never reach
+ *   it. The order minimum is checked before this discount. `orderRulesCombineWithPromotions`
+ *   (off by default): on, the discount and the store's coupons and promotions add up; off, a
+ *   coupon or promotion on the order wins and the list's rules step aside for that order.
+ * - **Times** are ISO-8601 instants in UTC (`startsAt`, `endsAt`).
+ * - **A list locked to an order** (an order's one-time discount, read as `Order.priceList`) is
+ *   never answered here: `get` answers `null`, and every write refuses it
+ *   `PRICE_LIST_LOCKED_TO_ORDER` (`BusinessRuleError`, 422). Change it from its order
+ *   (`orders.setOneTimeDiscounts`).
+ * - **Organizations:** a price list is the store's own row; a workspace's lists price only the
+ *   workspace.
+ *
+ * Permissions: reads need `ReadCatalog`, writes `UpdateCatalog` (deleting too, as the engine's
+ * single door asks). The names behind assignments also need `ReadCustomer` (a customer) or
+ * `ReadCustomer`/`ReadCustomerGroup` (a group); without it the name is `null` and the id stays.
+ */
+import { pageFromVendureList, readOffsetCursor, ValidationError, } from '@sixtyninecommerce/core';
+import { assertDeleted, DELETION_FIELDS, fieldOf, } from '../catalog/types.js';
+import { redactionWatcher } from '../customer-data-redaction.js';
+/**
+ * What a list search matches the term against:
+ * - `all` (the default): every facet below;
+ * - `name`: the list's own name and description;
+ * - `sku`: lists pricing a variant whose SKU STARTS WITH the term;
+ * - `product`: lists pricing a product or variant whose name contains the term;
+ * - `customer`: lists assigned to a matching customer, directly or through a group holding them
+ *   (or a group whose name matches).
+ * `sku` and `product` reach a list through variant, product, collection and facet-value entries
+ * alike. A list that prices everything (a default discount, or assigned to every customer) is
+ * never matched: it would answer every search.
+ */
+export const PRICE_LIST_SEARCH_MODES = ['all', 'name', 'sku', 'product', 'customer'];
+/** What an entries search matches: the entry's own label, or (`sku`) every entry pricing the SKU. */
+export const PRICE_LIST_ENTRY_SEARCH_MODES = ['all', 'sku'];
+/** The engine's `adminListQueryLimit`: a larger page of lists is refused. */
+export const MAX_PRICE_LIST_LIST_TAKE = 1000;
+/** The largest page of entries the engine answers. */
+export const MAX_PRICE_LIST_ENTRY_TAKE = 200;
+/** How many entries `entries.export` answers at most; `total` still counts every match. */
+export const MAX_PRICE_LIST_ENTRY_EXPORT = 10_000;
+/** How many lists one `bulk` call may name. */
+export const MAX_BULK_PRICE_LISTS = 100;
+/** A search term shorter than this is ignored by the engine: the whole list answers. */
+export const PRICE_LIST_SEARCH_MIN_TERM_LENGTH = 2;
+/** How many entries `forCustomer` answers per list at most (`entriesTake`). */
+export const MAX_CUSTOMER_PRICE_LIST_ENTRIES = 100;
+export const PRICE_LIST_BULK_ACTIONS = [
+    'ENABLE',
+    'DISABLE',
+    'DELETE',
+];
+const FIELDS = /* GraphQL */ `
+  id
+  name
+  description
+  isContract
+  priority
+  defaultDiscountBps
+  startsAt
+  endsAt
+  enabled
+  appliesToAllCustomers
+  paymentTermsDays
+  paymentTermsCode
+  minOrderAmount
+  minOrderAmountBasis
+  minOrderQuantity
+  orderRulesCombineWithPromotions
+  createdAt
+  updatedAt
+`;
+const ASSIGNMENT_FIELDS = /* GraphQL */ `
+  id
+  priceListId
+  customerGroupId
+  customerId
+  customerGroup {
+    id
+    name
+  }
+  customer {
+    id
+    firstName
+    lastName
+    emailAddress
+    company
+  }
+  createdAt
+  updatedAt
+`;
+/** A list as `get`, `create` and `update` read it: with its assignments' names. */
+export const PRICE_LIST_FIELDS = /* GraphQL */ `
+  ${FIELDS}
+  assignments { ${ASSIGNMENT_FIELDS} }
+`;
+export const PRICE_LISTS_QUERY = /* GraphQL */ `
+  query PriceLists($options: PriceListListOptions) {
+    priceLists(options: $options) {
+      items {
+        ${FIELDS}
+        assignments {
+          id
+          priceListId
+          customerGroupId
+          customerId
+        }
+        searchMatches {
+          kind
+          label
+        }
+        searchMatchCount
+      }
+      totalItems
+    }
+  }
+`;
+export const PRICE_LIST_QUERY = /* GraphQL */ `
+  query PriceList($id: ID!) {
+    priceList(id: $id) { ${PRICE_LIST_FIELDS} }
+  }
+`;
+export const CREATE_PRICE_LIST_MUTATION = /* GraphQL */ `
+  mutation CreatePriceList($input: CreatePriceListInput!) {
+    createPriceList(input: $input) { ${PRICE_LIST_FIELDS} }
+  }
+`;
+export const UPDATE_PRICE_LIST_MUTATION = /* GraphQL */ `
+  mutation UpdatePriceList($id: ID!, $input: UpdatePriceListInput!) {
+    updatePriceList(id: $id, input: $input) { ${PRICE_LIST_FIELDS} }
+  }
+`;
+export const DELETE_PRICE_LIST_MUTATION = /* GraphQL */ `
+  mutation DeletePriceList($id: ID!) {
+    deletePriceList(id: $id) { ${DELETION_FIELDS} }
+  }
+`;
+export const ASSIGN_PRICE_LIST_MUTATION = /* GraphQL */ `
+  mutation AssignPriceList($priceListId: ID!, $input: AssignPriceListInput!) {
+    assignPriceList(priceListId: $priceListId, input: $input) { ${ASSIGNMENT_FIELDS} }
+  }
+`;
+export const UNASSIGN_PRICE_LIST_MUTATION = /* GraphQL */ `
+  mutation UnassignPriceList($assignmentId: ID!) {
+    unassignPriceList(assignmentId: $assignmentId) { ${DELETION_FIELDS} }
+  }
+`;
+export const BULK_PRICE_LIST_ACTION_MUTATION = /* GraphQL */ `
+  mutation BulkPriceListAction($input: BulkPriceListActionInput!) {
+    bulkPriceListAction(input: $input) {
+      items {
+        id
+        status
+        code
+        message
+      }
+    }
+  }
+`;
+const ENTRY_WRITE_FIELDS = /* GraphQL */ `
+  id
+  priceListId
+  discountType
+  targetType
+  variantId
+  productId
+  collectionId
+  facetValueId
+  discountValue
+  chainValues
+  minQuantity
+  currencyCode
+  createdAt
+  updatedAt
+`;
+const ENTRY_FIELDS = /* GraphQL */ `
+  ${ENTRY_WRITE_FIELDS}
+  variantName
+  variantSku
+  targetName
+`;
+export const PRICE_LIST_ENTRIES_QUERY = /* GraphQL */ `
+  query PriceListEntries($priceListId: ID!, $options: PriceListEntryListOptions) {
+    priceListEntries(priceListId: $priceListId, options: $options) {
+      items { ${ENTRY_FIELDS} }
+      totalItems
+    }
+  }
+`;
+const FACET_COUNT_FIELDS = 'id label count';
+export const PRICE_LIST_ENTRY_FACETS_QUERY = /* GraphQL */ `
+  query PriceListEntryFacets($priceListId: ID!, $search: String, $searchMode: String) {
+    priceListEntryFacets(priceListId: $priceListId, search: $search, searchMode: $searchMode) {
+      targetTypes { ${FACET_COUNT_FIELDS} }
+      collections { ${FACET_COUNT_FIELDS} }
+      facetValues { ${FACET_COUNT_FIELDS} }
+      total
+    }
+  }
+`;
+export const SET_PRICE_LIST_ENTRY_MUTATION = /* GraphQL */ `
+  mutation SetPriceListEntry($priceListId: ID!, $input: SetPriceListEntryInput!) {
+    setPriceListEntry(priceListId: $priceListId, input: $input) { ${ENTRY_FIELDS} }
+  }
+`;
+export const BULK_SET_PRICE_LIST_ENTRIES_MUTATION = /* GraphQL */ `
+  mutation BulkSetPriceListEntries($priceListId: ID!, $entries: [SetPriceListEntryInput!]!) {
+    bulkSetPriceListEntries(priceListId: $priceListId, entries: $entries) {
+      ${ENTRY_WRITE_FIELDS}
+    }
+  }
+`;
+export const REMOVE_PRICE_LIST_ENTRY_MUTATION = /* GraphQL */ `
+  mutation RemovePriceListEntry($id: ID!) {
+    removePriceListEntry(id: $id) { ${DELETION_FIELDS} }
+  }
+`;
+const ORDER_RULE_FIELDS = /* GraphQL */ `
+  id
+  priceListId
+  discountType
+  conditionType
+  conditionValue
+  discountValue
+  createdAt
+  updatedAt
+`;
+export const PRICE_LIST_ORDER_RULES_QUERY = /* GraphQL */ `
+  query PriceListOrderRules($priceListId: ID!) {
+    priceListOrderRules(priceListId: $priceListId) { ${ORDER_RULE_FIELDS} }
+  }
+`;
+export const SET_PRICE_LIST_ORDER_RULE_MUTATION = /* GraphQL */ `
+  mutation SetPriceListOrderRule($priceListId: ID!, $input: SetPriceListOrderRuleInput!) {
+    setPriceListOrderRule(priceListId: $priceListId, input: $input) { ${ORDER_RULE_FIELDS} }
+  }
+`;
+export const REMOVE_PRICE_LIST_ORDER_RULE_MUTATION = /* GraphQL */ `
+  mutation RemovePriceListOrderRule($id: ID!) {
+    removePriceListOrderRule(id: $id) { ${DELETION_FIELDS} }
+  }
+`;
+export const CUSTOMER_PRICE_LISTS_QUERY = /* GraphQL */ `
+  query CustomerPriceLists($customerId: ID!, $options: CustomerPriceListsOptions) {
+    customerPriceLists(customerId: $customerId, options: $options) {
+      priceList { ${FIELDS} }
+      assignmentType
+      entries {
+        items { ${ENTRY_FIELDS} }
+        totalItems
+      }
+      orderRules { ${ORDER_RULE_FIELDS} }
+    }
+  }
+`;
+const DEFAULT_LIST_TAKE = 25;
+const DEFAULT_ENTRY_TAKE = 50;
+function invalid(code, message) {
+    return new ValidationError({ code, message, status: 400, service: 'vendure' });
+}
+const invalidListOptions = (message) => invalid('INVALID_PRICE_LIST_LIST_OPTIONS', message);
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isIdList = (value) => Array.isArray(value) && value.every((id) => typeof id === 'string');
+const isWhole = (value, min, max) => typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max;
+/** The page of one list call: `skip` or `after`, and `take` (else `limit`) within `max`. */
+function pageOf(options, defaultTake, max) {
+    if (options?.after !== undefined && options.skip !== undefined) {
+        throw invalidListOptions('Page with after or with skip, not both.');
+    }
+    const take = options?.take ?? options?.limit ?? defaultTake;
+    const skip = options?.skip ?? (options?.after === undefined ? 0 : readOffsetCursor(options.after));
+    if (!isWhole(take, 1, max)) {
+        throw invalidListOptions(`take must be a whole number from 1 to ${String(max)}.`);
+    }
+    if (!isWhole(skip, 0, Number.MAX_SAFE_INTEGER)) {
+        throw invalidListOptions('skip must be a whole number of 0 or more.');
+    }
+    return { skip, take };
+}
+/** A list search as the engine reads it; a term it would ignore is not sent. */
+function searchOf(options) {
+    const mode = options?.searchMode;
+    if (mode !== undefined && !PRICE_LIST_SEARCH_MODES.includes(mode)) {
+        throw invalidListOptions(`searchMode must be one of ${PRICE_LIST_SEARCH_MODES.join(', ')}.`);
+    }
+    const search = options?.search;
+    if (search === undefined)
+        return {};
+    if (typeof search !== 'string')
+        throw invalidListOptions('search must be a string.');
+    const term = search.trim();
+    if (term.length < PRICE_LIST_SEARCH_MIN_TERM_LENGTH)
+        return {};
+    return { search: term, ...(mode === undefined ? {} : { searchMode: mode }) };
+}
+/** An `assignedTo` filter as the engine reads it, or nothing; exactly one target, else refused. */
+function assignedToOf(options) {
+    const assignedTo = options?.assignedTo;
+    if (assignedTo === undefined)
+        return {};
+    const refused = () => invalidListOptions('assignedTo names exactly one of customerId and customerGroupId.');
+    if (!isObject(assignedTo))
+        throw refused();
+    const { customerId, customerGroupId, includeChannelWide } = assignedTo;
+    const hasCustomer = customerId !== undefined && customerId !== null;
+    const hasGroup = customerGroupId !== undefined && customerGroupId !== null;
+    if (hasCustomer === hasGroup)
+        throw refused();
+    const id = hasCustomer ? customerId : customerGroupId;
+    if (typeof id !== 'string' || id === '')
+        throw refused();
+    if (includeChannelWide !== undefined && typeof includeChannelWide !== 'boolean') {
+        throw invalidListOptions('assignedTo.includeChannelWide must be true or false.');
+    }
+    return {
+        filter: {
+            assignedTo: {
+                ...(hasCustomer ? { customerId: id } : { customerGroupId: id }),
+                ...(includeChannelWide === undefined ? {} : { includeChannelWide }),
+            },
+        },
+    };
+}
+/** An entries filter as the engine reads it; anything else is refused before it is sent. */
+function entryFilterOf(filter) {
+    if (filter === undefined)
+        return {};
+    const out = {};
+    const { targetType, search, searchMode, collectionIds, facetValueIds } = filter;
+    if (targetType !== undefined) {
+        if (!['variant', 'product', 'collection', 'facet_value'].includes(targetType)) {
+            throw invalidListOptions('targetType must be variant, product, collection or facet_value.');
+        }
+        out.targetType = targetType;
+    }
+    if (searchMode !== undefined) {
+        if (!PRICE_LIST_ENTRY_SEARCH_MODES.includes(searchMode)) {
+            throw invalidListOptions(`searchMode must be one of ${PRICE_LIST_ENTRY_SEARCH_MODES.join(', ')}.`);
+        }
+        out.searchMode = searchMode;
+    }
+    if (search !== undefined) {
+        if (typeof search !== 'string')
+            throw invalidListOptions('search must be a string.');
+        if (search.trim() !== '')
+            out.search = search.trim();
+    }
+    for (const [key, ids] of [
+        ['collectionIds', collectionIds],
+        ['facetValueIds', facetValueIds],
+    ]) {
+        if (ids === undefined)
+            continue;
+        if (!isIdList(ids))
+            throw invalidListOptions(`${key} must be a list of strings.`);
+        if (ids.length > 0)
+            out[key] = [...ids];
+    }
+    return out;
+}
+async function listPage(transport, skip, take, search, options) {
+    const redaction = redactionWatcher();
+    const data = await transport.graphql({
+        api: 'admin',
+        query: PRICE_LISTS_QUERY,
+        variables: { options: { skip, take, ...search } },
+        onExtensions: redaction.onExtensions,
+    }, options);
+    return pageFromVendureList({
+        items: data.priceLists.items.map((item) => redaction.mark({ ...item })),
+        totalItems: data.priceLists.totalItems,
+    }, skip, take, 
+    // Each following page re-sends the same search and per-call options.
+    (cursor) => listPage(transport, readOffsetCursor(cursor), take, search, options));
+}
+async function entriesPage(transport, priceListId, skip, take, filter, options) {
+    const data = await fieldOf(transport, PRICE_LIST_ENTRIES_QUERY, 'priceListEntries', { priceListId, options: { skip, take, ...filter } }, options);
+    return pageFromVendureList(data, skip, take, (cursor) => entriesPage(transport, priceListId, readOffsetCursor(cursor), take, filter, options));
+}
+/** A list read with its customers' names: each named customer is marked when withheld. */
+async function readList(transport, query, field, variables, options) {
+    const redaction = redactionWatcher();
+    const data = await transport.graphql({ api: 'admin', query, variables, onExtensions: redaction.onExtensions }, options);
+    const list = data[field] ?? null;
+    if (list === null)
+        return null;
+    return { ...list, assignments: list.assignments.map((row) => markCustomer(row, redaction)) };
+}
+function markCustomer(assignment, redaction) {
+    return assignment.customer === null
+        ? assignment
+        : {
+            ...assignment,
+            customer: redaction.mark({ ...assignment.customer }),
+        };
+}
+/** The largest value GraphQL's `Int` carries; the smallest is its negation minus one. */
+const GRAPHQL_INT_MAX = 2_147_483_647;
+/**
+ * An order rule's two values as the wire can carry them. `SetPriceListOrderRuleInput` types them
+ * `Int!`, so a fraction or a value outside 32 bits is answered by GraphQL's variable coercion with
+ * an uncoded `BAD_USER_INPUT` before the engine sees the rule, and the engine's own refusal (which
+ * names the field) never comes. The SDK refuses exactly those shapes the way the engine would,
+ * `PRICE_LIST_ORDER_RULE_INVALID` with a detail per field, before anything is sent. Every other
+ * rule (types, bounds, a discount below 1) stays the engine's.
+ */
+function assertRuleValuesFitTheWire(input) {
+    const problems = [];
+    for (const field of ['conditionValue', 'discountValue']) {
+        const value = isObject(input) ? input[field] : undefined;
+        if (typeof value !== 'number' || !Number.isInteger(value)) {
+            problems.push({
+                field,
+                code: 'VALUE_NOT_AN_INTEGER',
+                message: `${field} must be a whole number`,
+            });
+        }
+        else if (value > GRAPHQL_INT_MAX) {
+            problems.push({
+                field,
+                code: 'VALUE_TOO_LARGE',
+                message: `${field} must not exceed ${String(GRAPHQL_INT_MAX)}`,
+            });
+        }
+        else if (value < -GRAPHQL_INT_MAX - 1) {
+            problems.push(field === 'conditionValue'
+                ? { field, code: 'VALUE_NEGATIVE', message: 'conditionValue must not be negative' }
+                : {
+                    field,
+                    code: 'DISCOUNT_NOT_POSITIVE',
+                    message: 'discountValue must be at least 1: a rule must take something off',
+                });
+        }
+    }
+    const first = problems[0];
+    if (first === undefined)
+        return;
+    throw new ValidationError({
+        code: 'PRICE_LIST_ORDER_RULE_INVALID',
+        message: first.message,
+        status: 400,
+        service: 'vendure',
+        details: problems,
+    });
+}
+/** The selection of a bulk call, checked as the engine checks it, before anything is sent. */
+function bulkVariables(input) {
+    const refused = (message) => invalid('BULK_ACTION_INPUT_INVALID', message);
+    if (!isObject(input))
+        throw refused('A bulk action needs an action and priceListIds.');
+    if (!PRICE_LIST_BULK_ACTIONS.includes(input.action)) {
+        throw refused(`action must be one of ${PRICE_LIST_BULK_ACTIONS.join(', ')}.`);
+    }
+    if (!isIdList(input.priceListIds))
+        throw refused('priceListIds must be a list of strings.');
+    const ids = input.priceListIds;
+    if (ids.length === 0)
+        throw refused('Name at least one price list.');
+    if (ids.length > MAX_BULK_PRICE_LISTS) {
+        throw refused(`A bulk action takes at most ${String(MAX_BULK_PRICE_LISTS)} price lists.`);
+    }
+    if (new Set(ids.map((id) => id.toLowerCase())).size !== ids.length) {
+        throw refused('Name each price list once.');
+    }
+    return { input: { action: input.action, priceListIds: [...ids] } };
+}
+export function createPricingPriceListsModule(transport) {
+    const entries = {
+        // `async`: a refused option rejects the promise, as an engine refusal does.
+        async list(priceListId, options) {
+            const { skip, take } = pageOf(options, DEFAULT_ENTRY_TAKE, MAX_PRICE_LIST_ENTRY_TAKE);
+            return entriesPage(transport, priceListId, skip, take, entryFilterOf(options), options);
+        },
+        async export(priceListId, filter, options) {
+            const data = await fieldOf(transport, PRICE_LIST_ENTRIES_QUERY, 'priceListEntries', { priceListId, options: { ...entryFilterOf(filter), export: true } }, options);
+            return { items: data.items, total: data.totalItems };
+        },
+        async facets(priceListId, search, options) {
+            const filter = entryFilterOf({ search: search?.search, searchMode: search?.searchMode });
+            return fieldOf(transport, PRICE_LIST_ENTRY_FACETS_QUERY, 'priceListEntryFacets', { priceListId, search: filter.search ?? null, searchMode: filter.searchMode ?? null }, options);
+        },
+        set(priceListId, input, options) {
+            return fieldOf(transport, SET_PRICE_LIST_ENTRY_MUTATION, 'setPriceListEntry', { priceListId, input }, options);
+        },
+        bulkSet(priceListId, inputs, options) {
+            return fieldOf(transport, BULK_SET_PRICE_LIST_ENTRIES_MUTATION, 'bulkSetPriceListEntries', { priceListId, entries: [...inputs] }, options);
+        },
+        async remove(entryId, options) {
+            const response = await fieldOf(transport, REMOVE_PRICE_LIST_ENTRY_MUTATION, 'removePriceListEntry', { id: entryId }, options);
+            assertDeleted('PRICE_LIST_ENTRY_NOT_DELETED', [response]);
+        },
+    };
+    const orderRules = {
+        list(priceListId, options) {
+            return fieldOf(transport, PRICE_LIST_ORDER_RULES_QUERY, 'priceListOrderRules', { priceListId }, options);
+        },
+        async set(priceListId, input, options) {
+            assertRuleValuesFitTheWire(input);
+            return fieldOf(transport, SET_PRICE_LIST_ORDER_RULE_MUTATION, 'setPriceListOrderRule', { priceListId, input }, options);
+        },
+        async remove(ruleId, options) {
+            const response = await fieldOf(transport, REMOVE_PRICE_LIST_ORDER_RULE_MUTATION, 'removePriceListOrderRule', { id: ruleId }, options);
+            assertDeleted('PRICE_LIST_ORDER_RULE_NOT_DELETED', [response]);
+        },
+    };
+    return {
+        async list(options) {
+            const { skip, take } = pageOf(options, DEFAULT_LIST_TAKE, MAX_PRICE_LIST_LIST_TAKE);
+            // The filter is sent only when asked for: an engine without it refuses the whole document.
+            const narrowed = { ...searchOf(options), ...assignedToOf(options) };
+            return listPage(transport, skip, take, narrowed, options);
+        },
+        async forCustomer(customerId, options) {
+            const { entriesTake, ...call } = options ?? {};
+            if (entriesTake !== undefined && !isWhole(entriesTake, 1, MAX_CUSTOMER_PRICE_LIST_ENTRIES)) {
+                throw invalidListOptions(`entriesTake must be a whole number from 1 to ${String(MAX_CUSTOMER_PRICE_LIST_ENTRIES)}.`);
+            }
+            const rows = await fieldOf(transport, CUSTOMER_PRICE_LISTS_QUERY, 'customerPriceLists', { customerId, options: entriesTake === undefined ? null : { entriesTake } }, call);
+            return rows.map((row) => ({
+                priceList: row.priceList,
+                assignmentType: row.assignmentType,
+                entries: { items: row.entries.items, total: row.entries.totalItems },
+                orderRules: row.orderRules,
+            }));
+        },
+        get(id, options) {
+            return readList(transport, PRICE_LIST_QUERY, 'priceList', { id }, options);
+        },
+        async create(input, options) {
+            if (!isObject(input) || typeof input.name !== 'string') {
+                throw invalid('INVALID_PRICE_LIST_INPUT', 'A price list needs a name.');
+            }
+            const list = await readList(transport, CREATE_PRICE_LIST_MUTATION, 'createPriceList', { input }, options);
+            return list;
+        },
+        async update(id, input, options) {
+            if (!isObject(input))
+                throw invalid('INVALID_PRICE_LIST_INPUT', 'input must be an object.');
+            const list = await readList(transport, UPDATE_PRICE_LIST_MUTATION, 'updatePriceList', { id, input }, options);
+            return list;
+        },
+        async delete(id, options) {
+            const response = await fieldOf(transport, DELETE_PRICE_LIST_MUTATION, 'deletePriceList', { id }, options);
+            assertDeleted('PRICE_LIST_NOT_DELETED', [response]);
+        },
+        async assign(priceListId, target, options) {
+            const named = isObject(target) ? target : {};
+            const groupId = named.customerGroupId;
+            const customerId = named.customerId;
+            if ((typeof groupId === 'string') === (typeof customerId === 'string')) {
+                throw invalid('INVALID_PRICE_LIST_INPUT', 'Assign a price list to exactly one customerGroupId or customerId.');
+            }
+            const redaction = redactionWatcher();
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ASSIGN_PRICE_LIST_MUTATION,
+                variables: {
+                    priceListId,
+                    input: typeof groupId === 'string' ? { customerGroupId: groupId } : { customerId },
+                },
+                onExtensions: redaction.onExtensions,
+            }, options);
+            return markCustomer(data.assignPriceList, redaction);
+        },
+        async unassign(assignmentId, options) {
+            const response = await fieldOf(transport, UNASSIGN_PRICE_LIST_MUTATION, 'unassignPriceList', { assignmentId }, options);
+            assertDeleted('PRICE_LIST_ASSIGNMENT_NOT_DELETED', [response]);
+        },
+        async bulk(input, options) {
+            const data = await fieldOf(transport, BULK_PRICE_LIST_ACTION_MUTATION, 'bulkPriceListAction', bulkVariables(input), options);
+            return data.items;
+        },
+        entries,
+        orderRules,
+    };
+}

package/dist/purchasing/alerts.d.ts

@@ -0,0 +1,89 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * A purchasing staff alert (purchase-orders spec §8.14), named as its email under Management →
+ * Notifications. A string on the wire: more alerts may come (a provider push failing, phase 6).
+ */
+export type PurchasingAlert = 'purchase_order_approval_requested' | 'purchase_order_lines_overdue' | 'reorder_suggestions_digest' | (string & {});
+/**
+ * What needs attention in the active store's purchasing, counted over its legal entity: the
+ * dashboard's nav badges and Overview cards.
+ */
+export interface PurchasingAlertSummary {
+    /** `YYYY-MM-DD` in the legal entity's time zone: the day overdue lines are judged against. */
+    localDay: string;
+    /**
+     * Purchase orders waiting for an approver: submitted above the approval threshold, or sent with
+     * a revision above it.
+     */
+    awaitingApproval: number;
+    /**
+     * Lines of sent purchase orders with something still to come whose expected day (the supplier's
+     * confirmed day, else the requested one) is before `localDay`.
+     */
+    overdueLines: number;
+    /** Sent purchase orders with at least one overdue line. */
+    overdueOrders: number;
+    /** Purchase orders awaiting approval or with an overdue line, each counted once. */
+    attentionOrders: number;
+    /** Reorder suggestions of the last compute that are listed (not dismissed). */
+    reorderSuggestions: number;
+    /** Of those, the ones the last compute found new (not suggested before, or grown). */
+    newReorderSuggestions: number;
+}
+/** Who one purchasing alert email goes to. */
+export interface PurchasingAlertRecipients {
+    alert: PurchasingAlert;
+    /**
+     * The permission whose holders get the alert when no addresses are set:
+     * `ApprovePurchaseOrder`, `UpdatePurchaseOrder` or `CreatePurchaseOrder`.
+     */
+    permission: string;
+    /** The addresses set for this alert; empty when it goes to the permission's holders. */
+    emails: string[];
+    /**
+     * Who the alert goes to now: the addresses set, else the administrators of the legal entity's
+     * stores holding the permission (never a platform administrator or an API credential).
+     */
+    recipients: string[];
+}
+/** One alert's addresses: up to 20; an empty list sends it to the permission's holders again. */
+export interface PurchasingAlertRecipientsInput {
+    alert: PurchasingAlert;
+    emails: string[];
+}
+export declare const PURCHASING_ALERT_SUMMARY_FIELDS = "\n  localDay\n  awaitingApproval\n  overdueLines\n  overdueOrders\n  attentionOrders\n  reorderSuggestions\n  newReorderSuggestions\n";
+export declare const PURCHASING_ALERT_RECIPIENTS_FIELDS = "\n  alert\n  permission\n  emails\n  recipients\n";
+export declare const PURCHASING_ALERTS_QUERY = "\n  query PurchasingAlerts {\n    purchasingAlerts { \n  localDay\n  awaitingApproval\n  overdueLines\n  overdueOrders\n  attentionOrders\n  reorderSuggestions\n  newReorderSuggestions\n }\n  }\n";
+export declare const PURCHASING_ALERT_RECIPIENTS_QUERY = "\n  query PurchasingAlertRecipients {\n    purchasingAlertRecipients { \n  alert\n  permission\n  emails\n  recipients\n }\n  }\n";
+export declare const UPDATE_PURCHASING_ALERT_RECIPIENTS_MUTATION = "\n  mutation UpdatePurchasingAlertRecipients(\n    $input: [PurchasingAlertRecipientsInput!]!\n    $idempotencyKey: String\n  ) {\n    updatePurchasingAlertRecipients(input: $input, idempotencyKey: $idempotencyKey) {\n      \n  alert\n  permission\n  emails\n  recipients\n\n    }\n  }\n";
+export interface PurchasingAlertRecipientsModule {
+    /**
+     * Who each alert goes to, in a fixed order (approval requests, overdue lines, reorder digest).
+     * Needs `ManagePurchasingSettings`.
+     */
+    list(call?: Call): Promise<PurchasingAlertRecipients[]>;
+    /**
+     * Sets who the named alerts go to; an alert not named keeps its own, and an empty `emails`
+     * sends it to the permission's holders again. Answers every alert, as `list` does. Needs
+     * `ManagePurchasingSettings` on EVERY store of the legal entity (`SHARED_SELLER_NOT_ALLOWED`,
+     * 403). Refusals: `PURCHASING_SETTINGS_INVALID` (400: an unknown alert, an alert named twice, an
+     * address that is not one, more than 20 addresses).
+     */
+    update(input: PurchasingAlertRecipientsInput[], call?: Call): Promise<PurchasingAlertRecipients[]>;
+}
+/**
+ * `admin.purchasing.alerts` (purchase-orders spec §8.14): what needs attention in the legal
+ * entity's purchasing, and who its alert emails go to. Every method needs the Purchasing plugin
+ * (`PURCHASING_NOT_ENABLED`, 422) and a store that purchases (`HUB_HAS_NO_PURCHASING`,
+ * `LEGAL_ENTITY_REQUIRED`, 422).
+ */
+export interface PurchasingAlertsModule {
+    /**
+     * The counts behind the nav badges and the Overview cards. Needs `ReadPurchaseOrder`. `null`
+     * while purchasing is not switched on for the store's legal entity.
+     */
+    summary(call?: Call): Promise<PurchasingAlertSummary | null>;
+    recipients: PurchasingAlertRecipientsModule;
+}
+export declare function createPurchasingAlertsModule(transport: Transport): PurchasingAlertsModule;