@sixtyninecommerce/admin 0.9.0 → 0.11.0

package/dist/catalog/variant-find.js

@@ -0,0 +1,239 @@
+import { ValidationError } from '@sixtyninecommerce/core';
+import { createSearchModule, escapeSearchFilterValue } from '../search/index.js';
+import { fieldOf } from './types.js';
+/** The most variants one `variants.find` answers. */
+export const MAX_VARIANT_FIND_TAKE = 500;
+/** The most products one `variants.find` search reads (`take / perProduct`, rounded up). */
+export const MAX_VARIANT_FIND_PRODUCTS = 100;
+const FOUND_VARIANT_PRODUCT_FIELDS = /* GraphQL */ `
+  id
+  name
+  slug
+  featuredAsset {
+    id
+    preview
+  }
+`;
+/**
+ * What a picker reads of a variant. `storePrice`, never core's `price` / `priceWithTax`: those
+ * throw for a variant the store has no price for, and one such variant would empty the answer.
+ */
+export const FOUND_VARIANT_FIELDS = /* GraphQL */ `
+  id
+  name
+  sku
+  enabled
+  storePrice {
+    price
+    priceWithTax
+    currencyCode
+  }
+  trackInventory
+  outOfStockThreshold
+  useGlobalOutOfStockThreshold
+  stockOnHand
+  stockAllocated
+  stockLevels {
+    stockLocationId
+    stockOnHand
+    stockAllocated
+    stockLocation {
+      id
+      name
+    }
+  }
+`;
+/** A found variant with its product: the selection of every list that answers variants flat. */
+export const FOUND_VARIANT_WITH_PRODUCT_FIELDS = /* GraphQL */ `
+  ${FOUND_VARIANT_FIELDS}
+  product {
+    ${FOUND_VARIANT_PRODUCT_FIELDS}
+  }
+`;
+export const FIND_VARIANTS_BY_IDS_QUERY = /* GraphQL */ `
+  query CatalogFindVariantsByIds($options: ProductVariantListOptions) {
+    productVariants(options: $options) {
+      items {
+        ${FOUND_VARIANT_WITH_PRODUCT_FIELDS}
+      }
+      totalItems
+    }
+  }
+`;
+/**
+ * The variants of some products, bounded PER PRODUCT (`variantList`, never `variants`, which the
+ * engine answers whole and then cuts at 1,000 without saying so).
+ */
+export const FIND_VARIANTS_OF_PRODUCTS_QUERY = /* GraphQL */ `
+  query CatalogFindVariantsOfProducts(
+    $options: ProductListOptions
+    $variantOptions: ProductVariantListOptions
+  ) {
+    products(options: $options) {
+      items {
+        ${FOUND_VARIANT_PRODUCT_FIELDS}
+        variantList(options: $variantOptions) {
+          items {
+            ${FOUND_VARIANT_FIELDS}
+          }
+          totalItems
+        }
+      }
+      totalItems
+    }
+  }
+`;
+export function toFoundVariant(wire) {
+    const { stockLevels, product, ...rest } = wire;
+    return {
+        ...rest,
+        stockLevels: stockLevels.map((level) => ({
+            stockLocationId: level.stockLocationId,
+            stockLocationName: level.stockLocation?.name ?? '',
+            stockOnHand: level.stockOnHand,
+            stockAllocated: level.stockAllocated,
+        })),
+        product: {
+            id: product.id,
+            name: product.name,
+            slug: product.slug,
+            featuredAsset: product.featuredAsset,
+        },
+    };
+}
+function invalid(message) {
+    return new ValidationError({
+        code: 'VARIANT_FIND_INPUT_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+    });
+}
+function wholeNumber(value, low, high) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= low && value <= high;
+}
+/** A literal inside a regular expression the engine evaluates (Postgres `~*`). */
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function criterionOf(input) {
+    const given = ['ids', 'term', 'skuPrefix'].filter((key) => input[key] !== undefined);
+    if (given.length !== 1) {
+        throw invalid(`Say which variants with exactly one of ids, term and skuPrefix; got ${given.length === 0 ? 'none' : given.join(' and ')}.`);
+    }
+    if (input.ids !== undefined) {
+        if (!Array.isArray(input.ids) || input.ids.some((id) => typeof id !== 'string' || id === '')) {
+            throw invalid('ids must be a list of variant ids.');
+        }
+        return { kind: 'ids', ids: [...new Set(input.ids)] };
+    }
+    const key = input.term !== undefined ? 'term' : 'skuPrefix';
+    const text = input[key];
+    if (typeof text !== 'string' || text.trim() === '') {
+        throw invalid(`${key} must be text to search for; an empty one finds nothing.`);
+    }
+    return key === 'term'
+        ? { kind: 'term', term: text.trim() }
+        : { kind: 'skuPrefix', prefix: text.trim() };
+}
+/** The call's options with the currency the prices are asked in. */
+function pricedIn(options, currencyCode) {
+    if (currencyCode === undefined)
+        return options;
+    if (typeof currencyCode !== 'string' || currencyCode.trim() === '') {
+        throw invalid('currencyCode must be an ISO 4217 code, or left out for the store default.');
+    }
+    return { ...options, tenant: { ...options?.tenant, currency: currencyCode } };
+}
+async function findByIds(transport, ids, take, options) {
+    if (ids.length > take) {
+        throw invalid(`ids names ${String(ids.length)} variants and take is ${String(take)}. Raise take, or ask for fewer.`);
+    }
+    if (ids.length === 0)
+        return { items: [], products: [] };
+    const list = await fieldOf(transport, FIND_VARIANTS_BY_IDS_QUERY, 'productVariants', 
+    // Sorted so the engine's page is one total order; the answer is re-ordered below.
+    { options: { filter: { id: { in: ids } }, take: ids.length, sort: { id: 'ASC' } } }, options);
+    const found = new Map(list.items.map((row) => [row.id, row]));
+    return {
+        items: ids.flatMap((id) => {
+            const row = found.get(id);
+            return row ? [toFoundVariant(row)] : [];
+        }),
+        products: [],
+    };
+}
+async function findBySearch(transport, criterion, take, perProduct, options, pricedOptions) {
+    const productCount = Math.ceil(take / perProduct);
+    if (productCount > MAX_VARIANT_FIND_PRODUCTS) {
+        throw invalid(`take ${String(take)} at ${String(perProduct)} per product reads ${String(productCount)} products; at most ${String(MAX_VARIANT_FIND_PRODUCTS)}. Raise perProduct or lower take.`);
+    }
+    // Which products, and in what order, is the index's answer (`search.index`, never a copy of
+    // it): relevance for a term, the product's name for a SKU prefix.
+    const hits = await createSearchModule(transport).index('products', criterion.kind === 'term'
+        ? { term: criterion.term, take: productCount }
+        : {
+            term: '',
+            filters: [`skus STARTS WITH "${escapeSearchFilterValue(criterion.prefix)}"`],
+            sort: 'name',
+            take: productCount,
+        }, options);
+    const productIds = hits.items.map((hit) => hit.id);
+    if (productIds.length === 0)
+        return { items: [], products: [] };
+    const list = await fieldOf(transport, FIND_VARIANTS_OF_PRODUCTS_QUERY, 'products', {
+        options: { filter: { id: { in: productIds } }, take: productIds.length, sort: { id: 'ASC' } },
+        variantOptions: {
+            take: perProduct,
+            // A total order, so a bounded page is the same page on every read. By id alone: the
+            // engine applies the keys of a sort in the order its schema declares them, where `id`
+            // precedes `position`, so the `position, id` the pickers used to send was this order.
+            sort: { id: 'ASC' },
+            // Only a SKU search narrows the variants. A term matches the PRODUCT (its name, its
+            // description), and a variant's name is its options, so filtering variants by it would
+            // answer a product with nothing to pick.
+            ...(criterion.kind === 'skuPrefix'
+                ? { filter: { sku: { regex: `^${escapeRegex(criterion.prefix)}` } } }
+                : {}),
+        },
+    }, pricedOptions);
+    const read = new Map(list.items.map((product) => [product.id, product]));
+    const items = [];
+    const products = [];
+    for (const id of productIds) {
+        const room = take - items.length;
+        if (room <= 0)
+            break;
+        // The index can name a product the store no longer holds: it is updated after each change.
+        const product = read.get(id);
+        if (!product)
+            continue;
+        const rows = product.variantList.items.slice(0, room);
+        if (rows.length === 0)
+            continue;
+        for (const row of rows)
+            items.push(toFoundVariant({ ...row, product }));
+        products.push({ id: product.id, shown: rows.length, total: product.variantList.totalItems });
+    }
+    return { items, products };
+}
+/** `catalog.variants.find`; its contract is on `VariantsModule.find`. */
+export async function findVariants(transport, input, options) {
+    if (typeof input !== 'object' || input === null)
+        throw invalid('find takes an input object.');
+    const criterion = criterionOf(input);
+    const { take, perProduct } = input;
+    if (!wholeNumber(take, 1, MAX_VARIANT_FIND_TAKE)) {
+        throw invalid(`take must be a whole number from 1 to ${String(MAX_VARIANT_FIND_TAKE)}.`);
+    }
+    const pricedOptions = pricedIn(options, input.currencyCode);
+    if (criterion.kind === 'ids') {
+        if (perProduct !== undefined)
+            throw invalid('perProduct bounds a search; ids takes none.');
+        return findByIds(transport, criterion.ids, take, pricedOptions);
+    }
+    if (perProduct !== undefined && !wholeNumber(perProduct, 1, take)) {
+        throw invalid(`perProduct must be a whole number from 1 to take (${String(take)}).`);
+    }
+    return findBySearch(transport, criterion, take, perProduct ?? Math.ceil(take / 10), options, pricedOptions);
+}

package/dist/catalog/variants.d.ts

@@ -1,6 +1,7 @@
 import { type Page, type Transport } from '@sixtyninecommerce/core';
 import type { Call, ListOptions } from '../types.js';
-import { type AssetRef, type Availability, type AvailabilityInput, type FacetValueRef, type LanguageCode, type PriceBasis, type TranslationInput, type VariantAvailabilityState } from './types.js';
+import { type AssetRef, type Availability, type AvailabilityInput, type FacetValueRef, type LanguageCode, type PriceBasis, type TranslationInput, type VariantAvailabilityState, type WireAssetRef } from './types.js';
+import { type FindVariantsInput, type FoundVariants } from './variant-find.js';
 export interface StockLevel {
     stockLocationId: string;
     stockOnHand: number;
@@ -20,16 +21,43 @@ export type InventoryFlag = 'TRUE' | 'FALSE' | 'INHERIT';
  */
 export type ParcelPacking = 'shared' | 'separate' | 'none';
 /**
- * A product variant — the thing that has a SKU, a price and stock.
+ * A variant's backorder rule: `inherit` follows the store's, `deny` sells nothing below zero,
+ * `incoming` sells up to the stock on its way, `limited` up to `backorderLimit` below zero, and
+ * `unlimited` without a bound.
+ */
+export type VariantBackorderPolicy = 'inherit' | 'deny' | 'incoming' | 'limited' | 'unlimited';
+/** One currency's price of a variant: integer minor units, on the write's `priceBasis`. */
+export interface VariantPriceInput {
+    currencyCode: string;
+    price: number;
+}
+/**
+ * A variant's price in the active store, in the currency of the request (the store's default,
+ * unless the call names another with `tenant.currency`). Integer minor units of `currencyCode`.
  *
- * Money is integer minor units of `currencyCode`. On READ, `price` is ALWAYS
- * net and `priceWithTax` ALWAYS gross, whatever the store's basis — core
- * derives whichever side it does not store, at the rate of the store's default
- * tax zone. On WRITE, `price` is in the STORE's basis (`priceBasis`). So a
- * read-modify-write on a gross store (`pricesIncludeTax: true`) must start
- * from `priceWithTax`: writing back the `price` it read would drop the shelf
- * price by the whole VAT amount.
+ * `price` is ALWAYS net and `priceWithTax` ALWAYS gross, whatever the store's basis — core
+ * derives whichever side it does not store, at the rate of the store's default tax zone. A write
+ * states `price` in the STORE's basis (`priceBasis`), so a read-modify-write on a gross store
+ * (`pricesIncludeTax: true`) must start from `priceWithTax`: writing back the `price` it read
+ * would drop the shelf price by the whole VAT amount.
+ */
+export interface VariantStorePrice {
+    /** Net, always — never the figure to write back on a gross store. */
+    price: number;
+    /** Gross, always, at the store's default tax zone. */
+    priceWithTax: number;
+    currencyCode: string;
+}
+/**
+ * One price the store STORES for a variant, in one currency: integer minor units on the store's
+ * basis (gross on a store with `pricesIncludeTax`, net otherwise), exactly what a write takes. A
+ * currency the store converts from another has no entry; see {@link ProductVariant.storePrice}.
  */
+export interface VariantStoredPrice {
+    currencyCode: string;
+    price: number;
+}
+/** A product variant — the thing that has a SKU, a price and stock. */
 export interface ProductVariant extends Availability<VariantAvailabilityState> {
     id: string;
     productId: string;
@@ -39,11 +67,23 @@ export interface ProductVariant extends Availability<VariantAvailabilityState> {
     name: string;
     sku: string;
     enabled: boolean;
-    /** Net, always — never the figure to write back on a gross store. */
-    price: number;
-    /** Gross, always, at the store's default tax zone. */
-    priceWithTax: number;
-    currencyCode: string;
+    /**
+     * The prices the active store stores for the variant, one per currency (see
+     * {@link VariantStoredPrice}); `[]` when it stores none.
+     */
+    prices: VariantStoredPrice[];
+    /**
+     * The engine's on-hand total for the variant in the active store (core's `stockOnHand`, which
+     * per-location out-of-stock thresholds can adjust); `stockLevels` has the count at each location.
+     */
+    stockOnHand: number;
+    /**
+     * The variant's price in the active store, or null when the store has no price for it in the
+     * request's currency: none stored there and none it converts from. Never 0 for a missing price;
+     * a 0 here is a price of 0. Needs an engine with `ProductVariant.storePrice` (vendure-server
+     * at or after #1504).
+     */
+    storePrice: VariantStorePrice | null;
     taxCategory: {
         id: string;
         name: string;
@@ -69,6 +109,36 @@ export interface ProductVariant extends Availability<VariantAvailabilityState> {
     parcelCapacity: number | null;
     /** Never null on read: an unset packing is `shared`, the engine's default. */
     parcelPacking: ParcelPacking;
+    /** The fewest units one order line may carry; null for no minimum. */
+    minOrderQuantity: number | null;
+    /** The units a line's quantity moves in (6: 6, 12, 18 …); null for one. */
+    salesUnit: number | null;
+    /**
+     * Where the variant sits in its product's order (the dashboard's "Reorder"); null for a variant
+     * nobody placed, which {@link VariantsModule.list} puts after the placed ones.
+     */
+    position: number | null;
+    /**
+     * What one unit costs the store: NET, whatever the store's price basis (`prices` may be gross),
+     * integer minor units of its default currency; null when unset. Informational: no price or tax
+     * reads it.
+     */
+    cost: number | null;
+    packageWeightGrams: number | null;
+    packageLengthCm: number | null;
+    packageWidthCm: number | null;
+    packageHeightCm: number | null;
+    /**
+     * The variant's backorder rule; null follows the store's (`inherit`). A string on the wire: a
+     * newer engine may add a policy.
+     */
+    backorderPolicy: VariantBackorderPolicy | (string & {}) | null;
+    /** The units a `limited` variant may sell below zero; null when unset. */
+    backorderLimit: number | null;
+    /** GS1 barcode (the product-feeds plugin's identifier); null when unset. */
+    gtin: string | null;
+    /** Manufacturer part number; null when unset. */
+    mpn: string | null;
     stockLevels: StockLevel[];
     options: Array<{
         id: string;
@@ -128,6 +198,30 @@ interface VariantFields extends AvailabilityInput<VariantAvailabilityState> {
      * (`INVALID_PARCEL_PACKING`).
      */
     parcelPacking?: ParcelPacking | null;
+    /** The fewest units one order line may carry; null for no minimum. */
+    minOrderQuantity?: number | null;
+    /** The units a line's quantity moves in (6: 6, 12, 18 …); null for one. */
+    salesUnit?: number | null;
+    /**
+     * What one unit costs the store: NET, whatever the store's price basis, integer minor units of
+     * its default currency; null clears it.
+     */
+    cost?: number | null;
+    packageWeightGrams?: number | null;
+    packageLengthCm?: number | null;
+    packageWidthCm?: number | null;
+    packageHeightCm?: number | null;
+    /** Null: `inherit`. */
+    backorderPolicy?: VariantBackorderPolicy | null;
+    /** The units a `limited` variant may sell below zero. */
+    backorderLimit?: number | null;
+    /**
+     * GS1 barcode: 8, 12, 13 or 14 digits when new or changed (`FEED_IDENTIFIER_INVALID`
+     * otherwise); null or blank clears it. A stored value sent back unchanged is never judged.
+     */
+    gtin?: string | null;
+    /** Manufacturer part number; null or blank clears it. */
+    mpn?: string | null;
     stockLevels?: StockLevelInput[];
     trackInventory?: InventoryFlag;
     outOfStockThreshold?: number;
@@ -153,7 +247,7 @@ export interface VariantPriceSource {
     /**
      * What the store charges in this currency, in minor units, on the STORE's basis: gross on a
      * store with `pricesIncludeTax`, net otherwise — the basis a variant write takes, unlike
-     * {@link ProductVariant.price}, which reads net everywhere. Null when nothing prices it: no
+     * {@link VariantStorePrice.price}, which reads net everywhere. Null when nothing prices it: no
      * stored price and no EUR price or exchange rate to convert from, or a currency the store
      * marked not for sale.
      */
@@ -168,6 +262,41 @@ export interface VariantPriceSource {
     /** The organization that shares the variant with the store; null for the store's own variant. */
     organizationName: string | null;
 }
+/** A field {@link VariantsModule.list} can order a product's variants by. */
+export type VariantSortField = 'position' | 'name' | 'sku' | 'createdAt' | 'updatedAt';
+/** Options of {@link VariantsModule.list}. */
+export interface VariantListOptions extends ListOptions {
+    /**
+     * Only the variants whose SKU OR name (in the request's language) contains this text, case
+     * insensitively. Blank or omitted: every variant.
+     */
+    term?: string;
+    /**
+     * The order of the pages. Default `{ field: 'position', direction: 'ASC' }`: the order a
+     * merchant arranged the variants in, the ones never placed after the placed ones. The engine
+     * completes every sort with the variant id, so a page boundary never repeats or skips a row.
+     */
+    sort?: {
+        field: VariantSortField;
+        direction: 'ASC' | 'DESC';
+    };
+}
+/** The variants {@link VariantsModule.optionSets} reads at most by default. */
+export declare const DEFAULT_OPTION_SET_LIMIT = 1000;
+/** The most variants one {@link VariantsModule.optionSets} call reads. */
+export declare const MAX_OPTION_SET_LIMIT = 100000;
+/** The option combinations a product's variants already have, as far as they were read. */
+export interface VariantOptionSets {
+    /**
+     * One entry per variant read, in variant-id order: the ids of its options, sorted. A variant
+     * without options (a product's one default variant) reads `[]`.
+     */
+    combinations: string[][];
+    /** How many variants the product has in the store. */
+    totalItems: number;
+    /** The product has more variants than were read (`limit`): a combination absent here may exist. */
+    truncated: boolean;
+}
 /** The engine's bound on one `revertPrice` call (`MAX_REVERT_VARIANTS`). */
 export declare const MAX_REVERT_PRICE_VARIANTS = 500;
 export interface CreateProductVariantInput extends VariantFields {
@@ -179,6 +308,12 @@ export interface CreateProductVariantInput extends VariantFields {
 export interface UpdateProductVariantInput extends VariantFields {
     id: string;
     sku?: string;
+    /**
+     * The price in each named currency, integer minor units on `priceBasis` (required beside it,
+     * as for `price`). A currency left out keeps its price. Update only: the engine's create takes
+     * `price` alone and would drop this list without a word.
+     */
+    prices?: VariantPriceInput[];
 }
 /**
  * Variant writes. Reading needs `ReadCatalog`, creating `CreateCatalog`,
@@ -202,11 +337,99 @@ export interface UpdateProductVariantInput extends VariantFields {
  * refuses".
  */
 export interface VariantsModule {
-    list(productId: string, options?: ListOptions): Promise<Page<ProductVariant>>;
+    /**
+     * One page of a product's variants (`limit` 1 to 1,000, default 25), in the order `sort` names
+     * and filtered by `term`; `page.total` is how many match. `for await` walks every page. Needs
+     * `ReadCatalog` or `ReadProduct`. An id this store does not hold answers an empty page.
+     *
+     * Refused before sending: `INVALID_PAGE_SIZE` (`ValidationError`, 400) for a `limit` outside
+     * 1 to 1,000; `INVALID_VARIANT_SORT` (`ValidationError`, 400) for a sort field or direction
+     * this method does not name.
+     *
+     * @effect read
+     */
+    list(productId: string, options?: VariantListOptions): Promise<Page<ProductVariant>>;
+    /** @effect read */
     get(id: string, options?: Call): Promise<ProductVariant | null>;
-    /** All or nothing: the engine creates the batch in one transaction. */
+    /**
+     * The option combinations a product's variants already have, for a "create variants" form that
+     * must not offer a combination twice (the engine refuses one: "A ProductVariant with the
+     * selected options already exists"). Reads the variants in pages of up to 1,000, in id order, up
+     * to `limit` (default {@link DEFAULT_OPTION_SET_LIMIT}, at most {@link MAX_OPTION_SET_LIMIT});
+     * `truncated` says the product has more. Each page is one request: a high `limit` on a product
+     * with 100,000 variants is 100 of them. Needs `ReadCatalog` or `ReadProduct`; an id this store
+     * does not hold answers no combinations.
+     *
+     * Refused before sending: `INVALID_OPTION_SET_LIMIT` (`ValidationError`, 400) for a `limit`
+     * that is not a whole number from 1 to {@link MAX_OPTION_SET_LIMIT}.
+     *
+     * @effect read
+     */
+    optionSets(productId: string, options?: Call & {
+        limit?: number;
+    }): Promise<VariantOptionSets>;
+    /**
+     * The variants a picker offers, each with its store price, its stock and its product: by id
+     * (`ids`), by a full-text search (`term`) or by the start of a SKU (`skuPrefix`). Exactly one
+     * of the three.
+     *
+     * - **`ids`** answers exactly those variants, in the order asked. An id the store does not
+     *   hold is left out.
+     * - **A search reads products first**: the best `take / perProduct` products (rounded up) of
+     *   the store's product index, then at most `perProduct` variants of each, in a stable order
+     *   (by id; not the order a merchant arranged a product's variants in). `products` says per product how many of its variants match and how many `items` holds, so
+     *   a caller can tell a short product from a cut-off one. The index is updated by a job after
+     *   each change: a product created seconds ago may be missing.
+     * - **A hidden carrier variant is never answered**, by id or by search: the platform's own
+     *   variant behind externally priced order lines is not catalogue.
+     * - **A disabled or unpriced variant IS answered** (`enabled`, `storePrice: null`): the engine
+     *   refuses to add either to an order (`ORDER_LINE_VARIANT_UNPRICED` for the second).
+     *
+     * Needs `ReadCatalog` or `ReadProduct`. Refused before anything is sent
+     * (`VARIANT_FIND_INPUT_INVALID`, a `ValidationError`): none or several of `ids`, `term` and
+     * `skuPrefix`; a blank `term` or `skuPrefix`; `take` outside 1 to
+     * {@link MAX_VARIANT_FIND_TAKE}; `perProduct` outside 1 to `take`, or given with `ids`; more
+     * than {@link MAX_VARIANT_FIND_PRODUCTS} products; more distinct ids than `take`. By the
+     * engine: an id that is not an id at all (`ENTITY_NOT_FOUND`, a `NotFoundError`), a currency
+     * the store does not sell, and `SERVICE_UNAVAILABLE` (retryable) when the search service did
+     * not answer a search.
+     *
+     * @effect read
+     */
+    find(input: FindVariantsInput, options?: Call): Promise<FoundVariants>;
+    /**
+     * Create variants, all or nothing: the engine creates the batch in one transaction. Needs
+     * `CreateCatalog` or `CreateProduct`. A `price` travels with `priceBasis` (see
+     * {@link PriceBasis}); its other currencies are converted until a write stores them.
+     *
+     * Refusals (nothing is written), besides the option-combination and basis refusals above:
+     * - `TRANSLATION_INPUT_INVALID` → `ValidationError` (400): a translation without a name
+     *   (multi-region decision 106). One `details` entry per refused field, its message naming the
+     *   language; the entries carry no `field` pointer.
+     * - `TRANSLATION_LANGUAGE_NOT_OFFERED` → `BusinessRuleError` (422): a translation in a
+     *   language the store does not offer; `details[].field` points at the translation entry
+     *   (`/input/<n>/translations/<i>`).
+     * - `FEED_IDENTIFIER_INVALID` → `ValidationError` (400): a GTIN that is not 8, 12, 13 or 14
+     *   digits.
+     *
+     * @effect write
+     */
     create(inputs: CreateProductVariantInput[], options?: Call): Promise<ProductVariant[]>;
+    /** @effect write */
     update(inputs: UpdateProductVariantInput[], options?: Call): Promise<ProductVariant[]>;
+    /**
+     * Soft-delete variants: they are no longer listed, and orders keep the lines that name them.
+     * Nothing in this SDK restores one. Needs `DeleteCatalog` or `DeleteProduct`.
+     *
+     * Refused before anything is deleted: `ENTITY_NOT_FOUND` (`NotFoundError`, 404) for a variant
+     * this store does not hold; `SHARED_PRODUCT_VARIANT_NOT_ALLOWED` (`PermissionDeniedError`, 403)
+     * for one another store also holds that you may not change there; `FIELD_GROUP_LOCKED`
+     * (`BusinessRuleError`, 422) while an app or API token owns one of its field groups;
+     * `EXTERNAL_LINE_CARRIER_PROTECTED` (422) for the platform's carrier. A variant the engine
+     * declines is `VARIANT_NOT_DELETED` (`ConflictError`, 409) with its reasons.
+     *
+     * @effect destructive
+     */
     delete(ids: string[], options?: Call): Promise<void>;
     /**
      * Set stock on hand per stock location — absolute values, one update. A
@@ -248,27 +471,61 @@ export interface VariantsModule {
         currencyCodes?: readonly string[];
     }): Promise<ProductVariant[]>;
 }
-export declare const VARIANT_FIELDS = "\n  id\n  productId\n  createdAt\n  updatedAt\n  languageCode\n  name\n  sku\n  enabled\n  price\n  priceWithTax\n  currencyCode\n  taxCategory {\n    id\n    name\n  }\n  trackInventory\n  outOfStockThreshold\n  useGlobalOutOfStockThreshold\n  stockLevels {\n    stockLocationId\n    stockOnHand\n    stockAllocated\n  }\n  options {\n    id\n    code\n    name\n    groupId\n  }\n  featuredAsset { \n  id\n  name\n  preview\n  source\n }\n  assets { \n  id\n  name\n  preview\n  source\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n  customFields {\n    taxClassKey\n    availabilityState\n    availableFrom\n    preorderLimit\n    parcelCapacity\n    parcelPacking\n  }\n";
-export declare const VARIANTS_QUERY = "\n  query CatalogVariants($productId: ID!, $options: ProductVariantListOptions) {\n    productVariants(productId: $productId, options: $options) {\n      items { \n  id\n  productId\n  createdAt\n  updatedAt\n  languageCode\n  name\n  sku\n  enabled\n  price\n  priceWithTax\n  currencyCode\n  taxCategory {\n    id\n    name\n  }\n  trackInventory\n  outOfStockThreshold\n  useGlobalOutOfStockThreshold\n  stockLevels {\n    stockLocationId\n    stockOnHand\n    stockAllocated\n  }\n  options {\n    id\n    code\n    name\n    groupId\n  }\n  featuredAsset { \n  id\n  name\n  preview\n  source\n }\n  assets { \n  id\n  name\n  preview\n  source\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n  customFields {\n    taxClassKey\n    availabilityState\n    availableFrom\n    preorderLimit\n    parcelCapacity\n    parcelPacking\n  }\n }\n      totalItems\n    }\n  }\n";
-export declare const VARIANT_QUERY = "\n  query CatalogVariant($id: ID!) {\n    productVariant(id: $id) { \n  id\n  productId\n  createdAt\n  updatedAt\n  languageCode\n  name\n  sku\n  enabled\n  price\n  priceWithTax\n  currencyCode\n  taxCategory {\n    id\n    name\n  }\n  trackInventory\n  outOfStockThreshold\n  useGlobalOutOfStockThreshold\n  stockLevels {\n    stockLocationId\n    stockOnHand\n    stockAllocated\n  }\n  options {\n    id\n    code\n    name\n    groupId\n  }\n  featuredAsset { \n  id\n  name\n  preview\n  source\n }\n  assets { \n  id\n  name\n  preview\n  source\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n  customFields {\n    taxClassKey\n    availabilityState\n    availableFrom\n    preorderLimit\n    parcelCapacity\n    parcelPacking\n  }\n }\n  }\n";
-export declare const CREATE_VARIANTS_MUTATION = "\n  mutation CatalogCreateVariants($input: [CreateProductVariantInput!]!) {\n    createProductVariants(input: $input) { \n  id\n  productId\n  createdAt\n  updatedAt\n  languageCode\n  name\n  sku\n  enabled\n  price\n  priceWithTax\n  currencyCode\n  taxCategory {\n    id\n    name\n  }\n  trackInventory\n  outOfStockThreshold\n  useGlobalOutOfStockThreshold\n  stockLevels {\n    stockLocationId\n    stockOnHand\n    stockAllocated\n  }\n  options {\n    id\n    code\n    name\n    groupId\n  }\n  featuredAsset { \n  id\n  name\n  preview\n  source\n }\n  assets { \n  id\n  name\n  preview\n  source\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n  customFields {\n    taxClassKey\n    availabilityState\n    availableFrom\n    preorderLimit\n    parcelCapacity\n    parcelPacking\n  }\n }\n  }\n";
-export declare const UPDATE_VARIANTS_MUTATION = "\n  mutation CatalogUpdateVariants($input: [UpdateProductVariantInput!]!) {\n    updateProductVariants(input: $input) { \n  id\n  productId\n  createdAt\n  updatedAt\n  languageCode\n  name\n  sku\n  enabled\n  price\n  priceWithTax\n  currencyCode\n  taxCategory {\n    id\n    name\n  }\n  trackInventory\n  outOfStockThreshold\n  useGlobalOutOfStockThreshold\n  stockLevels {\n    stockLocationId\n    stockOnHand\n    stockAllocated\n  }\n  options {\n    id\n    code\n    name\n    groupId\n  }\n  featuredAsset { \n  id\n  name\n  preview\n  source\n }\n  assets { \n  id\n  name\n  preview\n  source\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n  customFields {\n    taxClassKey\n    availabilityState\n    availableFrom\n    preorderLimit\n    parcelCapacity\n    parcelPacking\n  }\n }\n  }\n";
+export declare const VARIANT_FIELDS = "\n  id\n  productId\n  createdAt\n  updatedAt\n  languageCode\n  name\n  sku\n  enabled\n  storePrice {\n    price\n    priceWithTax\n    currencyCode\n  }\n  prices {\n    currencyCode\n    price\n  }\n  stockOnHand\n  taxCategory {\n    id\n    name\n  }\n  trackInventory\n  outOfStockThreshold\n  useGlobalOutOfStockThreshold\n  stockLevels {\n    stockLocationId\n    stockOnHand\n    stockAllocated\n  }\n  options {\n    id\n    code\n    name\n    groupId\n  }\n  featuredAsset { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n  customFields {\n    altText\n  }\n }\n  assets { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n  customFields {\n    altText\n  }\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n  customFields {\n    taxClassKey\n    availabilityState\n    availableFrom\n    preorderLimit\n    parcelCapacity\n    parcelPacking\n    minOrderQuantity\n    salesUnit\n    position\n    cost\n    packageWeightGrams\n    packageLengthCm\n    packageWidthCm\n    packageHeightCm\n    backorderPolicy\n    backorderLimit\n    gtin\n    mpn\n  }\n";
+export declare const VARIANTS_QUERY = "\n  query CatalogVariants($productId: ID!, $options: ProductVariantListOptions) {\n    productVariants(productId: $productId, options: $options) {\n      items { \n  id\n  productId\n  createdAt\n  updatedAt\n  languageCode\n  name\n  sku\n  enabled\n  storePrice {\n    price\n    priceWithTax\n    currencyCode\n  }\n  prices {\n    currencyCode\n    price\n  }\n  stockOnHand\n  taxCategory {\n    id\n    name\n  }\n  trackInventory\n  outOfStockThreshold\n  useGlobalOutOfStockThreshold\n  stockLevels {\n    stockLocationId\n    stockOnHand\n    stockAllocated\n  }\n  options {\n    id\n    code\n    name\n    groupId\n  }\n  featuredAsset { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n  customFields {\n    altText\n  }\n }\n  assets { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n  customFields {\n    altText\n  }\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n  customFields {\n    taxClassKey\n    availabilityState\n    availableFrom\n    preorderLimit\n    parcelCapacity\n    parcelPacking\n    minOrderQuantity\n    salesUnit\n    position\n    cost\n    packageWeightGrams\n    packageLengthCm\n    packageWidthCm\n    packageHeightCm\n    backorderPolicy\n    backorderLimit\n    gtin\n    mpn\n  }\n }\n      totalItems\n    }\n  }\n";
+/** Two fields a row, for {@link VariantsModule.optionSets}: the id and its options' ids. */
+export declare const VARIANT_OPTION_SETS_QUERY = "\n  query CatalogVariantOptionSets($productId: ID!, $options: ProductVariantListOptions) {\n    productVariants(productId: $productId, options: $options) {\n      items {\n        id\n        options {\n          id\n        }\n      }\n      totalItems\n    }\n  }\n";
+export declare const VARIANT_QUERY = "\n  query CatalogVariant($id: ID!) {\n    productVariant(id: $id) { \n  id\n  productId\n  createdAt\n  updatedAt\n  languageCode\n  name\n  sku\n  enabled\n  storePrice {\n    price\n    priceWithTax\n    currencyCode\n  }\n  prices {\n    currencyCode\n    price\n  }\n  stockOnHand\n  taxCategory {\n    id\n    name\n  }\n  trackInventory\n  outOfStockThreshold\n  useGlobalOutOfStockThreshold\n  stockLevels {\n    stockLocationId\n    stockOnHand\n    stockAllocated\n  }\n  options {\n    id\n    code\n    name\n    groupId\n  }\n  featuredAsset { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n  customFields {\n    altText\n  }\n }\n  assets { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n  customFields {\n    altText\n  }\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n  customFields {\n    taxClassKey\n    availabilityState\n    availableFrom\n    preorderLimit\n    parcelCapacity\n    parcelPacking\n    minOrderQuantity\n    salesUnit\n    position\n    cost\n    packageWeightGrams\n    packageLengthCm\n    packageWidthCm\n    packageHeightCm\n    backorderPolicy\n    backorderLimit\n    gtin\n    mpn\n  }\n }\n  }\n";
+export declare const CREATE_VARIANTS_MUTATION = "\n  mutation CatalogCreateVariants($input: [CreateProductVariantInput!]!) {\n    createProductVariants(input: $input) { \n  id\n  productId\n  createdAt\n  updatedAt\n  languageCode\n  name\n  sku\n  enabled\n  storePrice {\n    price\n    priceWithTax\n    currencyCode\n  }\n  prices {\n    currencyCode\n    price\n  }\n  stockOnHand\n  taxCategory {\n    id\n    name\n  }\n  trackInventory\n  outOfStockThreshold\n  useGlobalOutOfStockThreshold\n  stockLevels {\n    stockLocationId\n    stockOnHand\n    stockAllocated\n  }\n  options {\n    id\n    code\n    name\n    groupId\n  }\n  featuredAsset { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n  customFields {\n    altText\n  }\n }\n  assets { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n  customFields {\n    altText\n  }\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n  customFields {\n    taxClassKey\n    availabilityState\n    availableFrom\n    preorderLimit\n    parcelCapacity\n    parcelPacking\n    minOrderQuantity\n    salesUnit\n    position\n    cost\n    packageWeightGrams\n    packageLengthCm\n    packageWidthCm\n    packageHeightCm\n    backorderPolicy\n    backorderLimit\n    gtin\n    mpn\n  }\n }\n  }\n";
+export declare const UPDATE_VARIANTS_MUTATION = "\n  mutation CatalogUpdateVariants($input: [UpdateProductVariantInput!]!) {\n    updateProductVariants(input: $input) { \n  id\n  productId\n  createdAt\n  updatedAt\n  languageCode\n  name\n  sku\n  enabled\n  storePrice {\n    price\n    priceWithTax\n    currencyCode\n  }\n  prices {\n    currencyCode\n    price\n  }\n  stockOnHand\n  taxCategory {\n    id\n    name\n  }\n  trackInventory\n  outOfStockThreshold\n  useGlobalOutOfStockThreshold\n  stockLevels {\n    stockLocationId\n    stockOnHand\n    stockAllocated\n  }\n  options {\n    id\n    code\n    name\n    groupId\n  }\n  featuredAsset { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n  customFields {\n    altText\n  }\n }\n  assets { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n  customFields {\n    altText\n  }\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n  customFields {\n    taxClassKey\n    availabilityState\n    availableFrom\n    preorderLimit\n    parcelCapacity\n    parcelPacking\n    minOrderQuantity\n    salesUnit\n    position\n    cost\n    packageWeightGrams\n    packageLengthCm\n    packageWidthCm\n    packageHeightCm\n    backorderPolicy\n    backorderLimit\n    gtin\n    mpn\n  }\n }\n  }\n";
 export declare const DELETE_VARIANTS_MUTATION = "\n  mutation CatalogDeleteVariants($ids: [ID!]!) {\n    deleteProductVariants(ids: $ids) { \n  result\n  message\n }\n  }\n";
 /**
  * A document of its own, never a field of `VARIANT_FIELDS`: every other variant read keeps
  * working against an engine older than the field, and pays nothing for it.
  */
 export declare const VARIANT_PRICE_SOURCES_QUERY = "\n  query CatalogVariantPriceSources($id: ID!) {\n    productVariant(id: $id) {\n      id\n      priceSources {\n        currencyCode\n        price\n        source\n        organizationPrice\n        organizationName\n      }\n    }\n  }\n";
-export declare const REVERT_TO_ORGANIZATION_PRICE_MUTATION = "\n  mutation CatalogRevertToOrganizationPrice($variantIds: [ID!]!, $currencyCodes: [CurrencyCode!]) {\n    revertToOrganizationPrice(variantIds: $variantIds, currencyCodes: $currencyCodes) { \n  id\n  productId\n  createdAt\n  updatedAt\n  languageCode\n  name\n  sku\n  enabled\n  price\n  priceWithTax\n  currencyCode\n  taxCategory {\n    id\n    name\n  }\n  trackInventory\n  outOfStockThreshold\n  useGlobalOutOfStockThreshold\n  stockLevels {\n    stockLocationId\n    stockOnHand\n    stockAllocated\n  }\n  options {\n    id\n    code\n    name\n    groupId\n  }\n  featuredAsset { \n  id\n  name\n  preview\n  source\n }\n  assets { \n  id\n  name\n  preview\n  source\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n  customFields {\n    taxClassKey\n    availabilityState\n    availableFrom\n    preorderLimit\n    parcelCapacity\n    parcelPacking\n  }\n }\n  }\n";
+export declare const REVERT_TO_ORGANIZATION_PRICE_MUTATION = "\n  mutation CatalogRevertToOrganizationPrice($variantIds: [ID!]!, $currencyCodes: [CurrencyCode!]) {\n    revertToOrganizationPrice(variantIds: $variantIds, currencyCodes: $currencyCodes) { \n  id\n  productId\n  createdAt\n  updatedAt\n  languageCode\n  name\n  sku\n  enabled\n  storePrice {\n    price\n    priceWithTax\n    currencyCode\n  }\n  prices {\n    currencyCode\n    price\n  }\n  stockOnHand\n  taxCategory {\n    id\n    name\n  }\n  trackInventory\n  outOfStockThreshold\n  useGlobalOutOfStockThreshold\n  stockLevels {\n    stockLocationId\n    stockOnHand\n    stockAllocated\n  }\n  options {\n    id\n    code\n    name\n    groupId\n  }\n  featuredAsset { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n  customFields {\n    altText\n  }\n }\n  assets { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n  customFields {\n    altText\n  }\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n  customFields {\n    taxClassKey\n    availabilityState\n    availableFrom\n    preorderLimit\n    parcelCapacity\n    parcelPacking\n    minOrderQuantity\n    salesUnit\n    position\n    cost\n    packageWeightGrams\n    packageLengthCm\n    packageWidthCm\n    packageHeightCm\n    backorderPolicy\n    backorderLimit\n    gtin\n    mpn\n  }\n }\n  }\n";
 /** The price basis the store stores, read on the SAME tenant as the write. */
 export declare const PRICE_BASIS_QUERY = "\n  query CatalogPriceBasis {\n    activeChannel {\n      pricesIncludeTax\n    }\n  }\n";
-interface WireVariant extends Omit<ProductVariant, keyof Availability<string> | 'taxClassKey' | 'parcelCapacity' | 'parcelPacking'> {
-    customFields: (Partial<Availability<VariantAvailabilityState>> & {
+/** The variant fields read out of `customFields` as they are, null for an unset one. */
+export declare const LIFTED_CUSTOM_FIELDS: readonly ["minOrderQuantity", "salesUnit", "position", "cost", "packageWeightGrams", "packageLengthCm", "packageWidthCm", "packageHeightCm", "backorderPolicy", "backorderLimit", "gtin", "mpn"];
+type LiftedCustomField = (typeof LIFTED_CUSTOM_FIELDS)[number];
+interface WireVariant extends Omit<ProductVariant, keyof Availability<string> | 'taxClassKey' | 'parcelCapacity' | 'parcelPacking' | LiftedCustomField | 'featuredAsset' | 'assets'> {
+    featuredAsset: WireAssetRef | null;
+    assets: WireAssetRef[];
+    customFields: (Partial<Availability<VariantAvailabilityState>> & Partial<Pick<ProductVariant, LiftedCustomField>> & {
         taxClassKey?: string | null;
         parcelCapacity?: number | null;
         parcelPacking?: string | null;
     }) | null;
 }
+/** Lift the custom fields to first-class fields. */
 export declare function toVariant(wire: WireVariant): ProductVariant;
+/**
+ * The engine's `ProductVariantListOptions` for {@link VariantListOptions}, without the page
+ * window. ONE sort key, never a tie-breaker beside it: graphql-js coerces an input object in the
+ * order its TYPE declares the fields, and `ProductVariantSortParameter` declares `id` before every
+ * field named here, so `{ position, id }` reaches the engine as `{ id, position }` and sorts by id
+ * alone (W10-113 finding). The engine completes the order itself: `productVariants(productId:)`
+ * (core's `getVariantsByProductId`) appends `id ASC` after the caller's key, which makes it total,
+ * so offset pages neither repeat nor skip a row even where `position` is null.
+ */
+export declare function variantListOptions(options: VariantListOptions | undefined): {
+    sort: Record<string, 'ASC' | 'DESC'>;
+    filter?: Record<string, unknown>;
+    filterOperator?: 'OR';
+};
+/** A write's prices and the basis it states them on. */
+export interface PricedInput {
+    price?: number;
+    prices?: readonly VariantPriceInput[];
+    priceBasis?: PriceBasis;
+}
+/**
+ * Every priced input (`price`, or any `prices` entry) must be whole minor units and state its
+ * basis, and the basis must be the store's. Read per call, with the call's own options, so a
+ * per-call tenant is checked against ITS store rather than the client's default one.
+ */
+export declare function assertPricesStateBasis(transport: Transport, inputs: readonly PricedInput[], options?: Call): Promise<void>;
 export declare function createVariantsModule(transport: Transport): VariantsModule;
 export {};