@sixtyninecommerce/admin 0.10.0 → 0.12.0

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;
@@ -31,16 +32,32 @@ export interface VariantPriceInput {
     price: number;
 }
 /**
- * A product variant — the thing that has a SKU, a price and stock.
+ * 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;
@@ -50,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;
@@ -80,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;
@@ -143,7 +202,10 @@ interface VariantFields extends AvailabilityInput<VariantAvailabilityState> {
     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, integer minor units of its default currency; null clears it. */
+    /**
+     * 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;
@@ -185,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.
      */
@@ -200,6 +262,68 @@ 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. */
+/**
+ * Where a variant's pre-order date (`availableFrom`) comes from (purchase-orders spec §8.12.3):
+ * `manual`, the date staff set, or `incoming`, kept equal to the earliest confirmed delivery of an
+ * open purchase order into the store's storefront warehouses.
+ */
+export type AvailableFromSource = 'manual' | 'incoming';
+/** The sources {@link VariantsModule.setAvailableFromSource} sends. */
+export declare const AVAILABLE_FROM_SOURCES: readonly AvailableFromSource[];
+/** A variant's pre-order date source in the active store, and what `incoming` follows. */
+export interface VariantAvailableFromSource {
+    productVariantId: string;
+    /** A string on the wire: a newer engine may add a source. */
+    source: AvailableFromSource | (string & {});
+    /** The stored availability date, ISO-8601 UTC, whoever set it; null when unset. */
+    availableFrom: string | null;
+    /**
+     * The earliest future day (`YYYY-MM-DD`) a supplier confirmed for an open purchase order of the
+     * variant, the day `incoming` follows; null for "no confirmed purchase order" (the date then
+     * keeps its last value).
+     */
+    confirmedIncomingOn: string | null;
+    /**
+     * Stores of more than one legal entity hold the variant, or an organization does: it cannot
+     * follow the purchase orders (`incoming` is refused `AVAILABLE_FROM_SOURCE_SHARED_VARIANT`).
+     */
+    sharedAcrossLegalEntities: boolean;
+}
+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 {
@@ -240,11 +364,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
@@ -285,29 +497,84 @@ export interface VariantsModule {
     revertPrice(variantIds: string[], options?: Call & {
         currencyCodes?: readonly string[];
     }): Promise<ProductVariant[]>;
+    /**
+     * Where the variant's pre-order date comes from in the active store, the day a supplier
+     * confirmed that `incoming` would follow, and whether the variant may follow it at all
+     * (purchase-orders spec §8.12.3). Needs `ReadCatalog` or `ReadProduct` and the Purchasing
+     * plugin on the store (`PLUGIN_ACCESS_DENIED`, 403). A variant this store does not have is a
+     * `NotFoundError` (`PURCHASING_VARIANT_NOT_FOUND`).
+     *
+     * A document of its own, never a field of the variant reads: those keep working against an
+     * engine older than the field. Needs an engine with purchase orders step 5.3.
+     *
+     * @effect read
+     */
+    availableFromSource(variantId: string, options?: Call): Promise<VariantAvailableFromSource>;
+    /**
+     * Switches the variant's pre-order date between the date staff set (`manual`) and the earliest
+     * confirmed purchase-order delivery (`incoming`, recomputed at once and whenever a purchase
+     * order of the variant is confirmed, revised, received or cancelled). The date only takes effect
+     * under a variant availability state that is not `inherit`. Needs `UpdateCatalog` or
+     * `UpdateProduct` on every store holding the variant, and the Purchasing plugin. Answers the
+     * variant's source as {@link availableFromSource} reads it. Refusals:
+     * - `AVAILABLE_FROM_SOURCE_INVALID` → `ValidationError` (400): a source other than `manual` or
+     *   `incoming`; refused before sending too.
+     * - `PURCHASING_NOT_ENABLED` → `BusinessRuleError` (422): `incoming` while purchasing is off.
+     * - `AVAILABLE_FROM_SOURCE_SHARED_VARIANT` → `BusinessRuleError` (422): `incoming` for a
+     *   variant stores of several legal entities, or an organization, hold.
+     * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): a variant this store does not have.
+     *
+     * @effect write
+     */
+    setAvailableFromSource(variantId: string, source: AvailableFromSource, options?: Call): Promise<VariantAvailableFromSource>;
 }
-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";
+/** Its own document: see {@link VariantsModule.availableFromSource}. */
+export declare const VARIANT_AVAILABLE_FROM_SOURCE_QUERY = "\n  query CatalogVariantAvailableFromSource($productVariantId: ID!) {\n    variantAvailableFromSource(productVariantId: $productVariantId) {\n      \n  productVariantId\n  source\n  availableFrom\n  confirmedIncomingOn\n  sharedAcrossLegalEntities\n\n    }\n  }\n";
+export declare const SET_VARIANT_AVAILABLE_FROM_SOURCE_MUTATION = "\n  mutation CatalogSetVariantAvailableFromSource(\n    $input: SetVariantAvailableFromSourceInput!\n    $idempotencyKey: String\n  ) {\n    setVariantAvailableFromSource(input: $input, idempotencyKey: $idempotencyKey) {\n      \n  productVariantId\n  source\n  availableFrom\n  confirmedIncomingOn\n  sharedAcrossLegalEntities\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;