@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/catalog/products.d.ts

@@ -0,0 +1,650 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { JobHandle } from '../jobs/index.js';
+import type { Call, ListOptions } from '../types.js';
+import { type ProductBulkInput, type ProductBulkRun } from './products-bulk.js';
+import { type AssetRef, type Availability, type AvailabilityInput, type CatalogueOwnership, type FacetValueRef, type LanguageCode, type PriceBasis, type ProductAvailabilityState, type TranslationInput, type VariantAvailabilityState } from './types.js';
+import { type ParcelPacking, type VariantBackorderPolicy, type VariantPriceInput } from './variants.js';
+export interface ProductOptionRef {
+    id: string;
+    code: string;
+    name: string;
+}
+export interface ProductOptionGroupRef {
+    id: string;
+    code: string;
+    name: string;
+    options: ProductOptionRef[];
+}
+export interface ProductTranslation {
+    id: string;
+    languageCode: LanguageCode;
+    name: string;
+    slug: string;
+    description: string;
+}
+/**
+ * A product, in the language the call asked for (`TenantContext.language`,
+ * else the store's default). Variants are read separately
+ * (`catalog.variants.list(productId)`); `variantCount` says how many there are.
+ */
+export interface Product extends Availability<ProductAvailabilityState> {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    languageCode: LanguageCode;
+    name: string;
+    slug: string;
+    description: string;
+    enabled: boolean;
+    featuredAsset: AssetRef | null;
+    assets: AssetRef[];
+    facetValues: FacetValueRef[];
+    optionGroups: ProductOptionGroupRef[];
+    translations: ProductTranslation[];
+    variantCount: number;
+    /** The store's own product, or its organization's; see {@link CatalogueOwnership}. */
+    catalogueOwnership: CatalogueOwnership;
+    /**
+     * The ACTIVE store excludes this product its organization shares with it
+     * ({@link ProductsModule.exclude}): it is off the store's storefront and out of its carts,
+     * while the store's orders, returns and invoices keep it. Always false for the store's own
+     * product and in an organization's workspace.
+     */
+    excludedFromStore: boolean;
+}
+export interface ProductTranslationInput extends TranslationInput {
+    name?: string;
+    /** Vendure makes a slug unique within the store by suffixing it, rather than refusing a duplicate. */
+    slug?: string;
+    description?: string;
+}
+export interface CreateProductInput extends AvailabilityInput<ProductAvailabilityState> {
+    /** At least one; the store's default language is the one a shop falls back to. */
+    translations: ProductTranslationInput[];
+    /** Defaults to true on the engine. */
+    enabled?: boolean;
+    featuredAssetId?: string | null;
+    /** The product's assets, in display order. Replaces the list on update. */
+    assetIds?: string[];
+    /** Replaces the product's facet values on update — send the whole set. */
+    facetValueIds?: string[];
+    /**
+     * The brand feeds name; at most 70 characters when new or changed (`FEED_IDENTIFIER_INVALID`
+     * otherwise). Null or blank clears it. A stored value sent back unchanged is never judged.
+     */
+    brand?: string | null;
+    condition?: ProductCondition;
+}
+/** A product's condition, as feeds state it. */
+export type ProductCondition = 'new' | 'refurbished' | 'used';
+/** A PATCH: omitted fields are left alone. */
+export interface UpdateProductInput extends Partial<CreateProductInput> {
+    id: string;
+}
+/** Every key narrows the list; several are combined with AND. */
+export interface ProductListFilter {
+    ids?: string[];
+    /** Case-insensitive substring of the name in the requested language. */
+    name?: string;
+    /** Case-insensitive substring of any variant's SKU. */
+    sku?: string;
+    enabled?: boolean;
+    /** Products carrying ANY of these facet values. */
+    facetValueIds?: string[];
+    availabilityState?: ProductAvailabilityState;
+}
+export interface ProductListOptions extends ListOptions {
+    filter?: ProductListFilter;
+    sort?: {
+        field: 'name' | 'slug' | 'createdAt' | 'updatedAt';
+        direction: 'ASC' | 'DESC';
+    };
+}
+/** The engine's bound on one `exclude` or `include` call (`STORE_EXCLUSION_BATCH_LIMIT`). */
+export declare const MAX_STORE_EXCLUSION_PRODUCTS = 500;
+/**
+ * The engine's bounds on one `setAvailabilityInStores` or `availabilityInStores` call
+ * (`AVAILABILITY_*_LIMIT`).
+ */
+export declare const MAX_AVAILABILITY_PRODUCTS = 100;
+export declare const MAX_AVAILABILITY_STORES = 50;
+/**
+ * What {@link ProductsModule.setAvailabilityInStores} did to one product in one member store:
+ * `excluded` (off: kept by the store for its orders, off its storefront), `unlinked` (off, under
+ * the `selected` assortment, from a store that never sold or quoted it), `included` (on again)
+ * or `assigned` (on, in a store that did not hold it; its images and variants follow within
+ * moments). A string on the wire: a newer engine may add an action.
+ */
+export type OrganizationProductAvailabilityAction = 'excluded' | 'included' | 'unlinked' | 'assigned';
+export interface OrganizationProductAvailabilityChange {
+    productId: string;
+    /** The member store's channel id. */
+    channelId: string;
+    action: OrganizationProductAvailabilityAction | (string & {});
+}
+/**
+ * What a member store does with one of the workspace's products, as
+ * {@link ProductsModule.availabilityInStores} read it: `offered` (it holds the product and does
+ * not exclude it: the product's state, not a promise that a variant is buyable there), `excluded`
+ * (kept for its orders, off its storefront and carts; also a product excluded ahead of the
+ * organization's fan-out under the `all` assortment, not held yet) or `not-held` (never
+ * assigned, or unlinked). A string on the wire: a newer engine may add a state.
+ */
+export type OrganizationProductStoreState = 'offered' | 'excluded' | 'not-held';
+export interface OrganizationProductStoreAvailability {
+    productId: string;
+    /** The member store's channel id. */
+    channelId: string;
+    state: OrganizationProductStoreState | (string & {});
+    /**
+     * The store's own live local copy of this product ({@link ProductsModule.makeLocalCopy}), if
+     * it has one; null otherwise.
+     */
+    localCopyId: string | null;
+}
+export interface AvailabilityInStoresInput {
+    /** Products of the organization's workspace: 1 to {@link MAX_AVAILABILITY_PRODUCTS}. */
+    productIds: string[];
+    /** Member stores, by channel id: 1 to {@link MAX_AVAILABILITY_STORES}. */
+    channelIds: string[];
+}
+export interface SetAvailabilityInStoresInput {
+    /** Products of the organization's workspace: 1 to {@link MAX_AVAILABILITY_PRODUCTS}. */
+    productIds: string[];
+    /** Member stores, by channel id: 1 to {@link MAX_AVAILABILITY_STORES}. */
+    channelIds: string[];
+    /** True: offer the products in those stores; false: stop offering them there. */
+    available: boolean;
+}
+/** A SKU for the copy of one of the shared product's variants, taken as given or refused. */
+export interface LocalCopySkuInput {
+    /** The shared product's variant, as the store holds it. */
+    productVariantId: string;
+    /** Trimmed by the engine; at most 255 characters. */
+    sku: string;
+}
+/**
+ * What became of the organization's product in the store: `excluded` (the store sold or quoted
+ * it, or the organization offers every product: it keeps it for its orders, off its storefront)
+ * or `unlinked` (removed from the store). A string on the wire: a newer engine may add one.
+ */
+export type LocalCopyOriginalOutcome = 'excluded' | 'unlinked';
+export interface LocalCopyResult {
+    /** The store's own copy, created DISABLED. */
+    product: Product;
+    /** The organization's product the copy was made from. */
+    originalProductId: string;
+    original: LocalCopyOriginalOutcome | (string & {});
+    /**
+     * How many of the organization's properties had a value on the original: the copy does not
+     * carry them (only the store's own property groups are copied), so say so before enabling it.
+     */
+    droppedOrganizationPropertyCount: number;
+}
+/** The engine's bound on each list of one {@link ProductsModule.setCollections} call. */
+export declare const MAX_PRODUCT_COLLECTION_IDS = 200;
+/**
+ * Why a collection {@link ProductsModule.setCollections} was asked to take the product out of
+ * still holds it: `MEMBER_BY_FILTER`, the product is not on the collection's hand-picked list but
+ * matches its other filters (facet values, names), which the call never changes. A string on the
+ * wire: a newer engine may add a reason.
+ */
+export type ProductCollectionNotRemovedReason = 'MEMBER_BY_FILTER';
+/** What {@link ProductsModule.setCollections} did, per collection id, each list in id order. */
+export interface ProductCollectionsResult {
+    /** Collections whose hand-picked list now names the product. */
+    added: string[];
+    /** Collections whose hand-picked lists no longer name it. */
+    removed: string[];
+    /** Collections the call named (or, without `from`, found) that needed no write. */
+    unchanged: string[];
+    /** Collections the product was to leave but stays in. */
+    notRemoved: Array<{
+        collectionId: string;
+        reason: ProductCollectionNotRemovedReason | (string & {});
+    }>;
+}
+/** The product's own fields in a {@link ProductsModule.save}; a PATCH. */
+export interface SaveProductFieldsInput extends AvailabilityInput<ProductAvailabilityState> {
+    /** In the save's `languageCode`. */
+    name?: string;
+    slug?: string;
+    description?: string;
+    enabled?: boolean;
+    /** Null: no featured image. */
+    featuredAssetId?: string | null;
+    /** The product's images, in display order; replaces the list. */
+    assetIds?: string[];
+    /** At most 70 characters when new or changed; null or blank clears it. */
+    brand?: string | null;
+    condition?: ProductCondition;
+}
+/**
+ * One variant in a {@link ProductsModule.save}; a PATCH. A price (`price` or `prices`) travels
+ * with `priceBasis`, the store's basis, exactly as for `catalog.variants.update`.
+ */
+export interface SaveProductVariantInput extends AvailabilityInput<VariantAvailabilityState> {
+    id: string;
+    /** In the save's `languageCode`; trimmed. */
+    name?: string;
+    sku?: string;
+    enabled?: boolean;
+    /** Integer minor units of the store's default currency. */
+    price?: number;
+    /**
+     * The price in each named currency. A currency left out keeps its stored price (the list
+     * removes nothing), and one equal to what is stored is no change. Its default-currency entry
+     * must equal `price` when both are sent.
+     */
+    prices?: VariantPriceInput[];
+    priceBasis?: PriceBasis;
+    taxCategoryId?: string;
+    /** Compared as a set. */
+    facetValueIds?: string[];
+    /** Null: no featured image. */
+    featuredAssetId?: string | null;
+    assetIds?: string[];
+    minOrderQuantity?: number | null;
+    salesUnit?: number | null;
+    /** Integer minor units of the store's default currency. */
+    cost?: number | null;
+    packageWeightGrams?: number | null;
+    packageLengthCm?: number | null;
+    packageWidthCm?: number | null;
+    packageHeightCm?: number | null;
+    /** 1 to 10,000; null: the store's items per parcel. */
+    parcelCapacity?: number | null;
+    /** Null: `shared`. */
+    parcelPacking?: ParcelPacking | null;
+    /** Null: `inherit`. */
+    backorderPolicy?: VariantBackorderPolicy | null;
+    backorderLimit?: number | null;
+    /** 8, 12, 13 or 14 digits when new or changed; null or blank clears it. */
+    gtin?: string | null;
+    mpn?: string | null;
+}
+/** One property value in a {@link ProductsModule.save}. */
+export interface SaveProductPropertyValueInput {
+    propertyId: string;
+    /** A translatable property's language; the save's `languageCode` when left out. */
+    languageCode?: LanguageCode;
+    /** Null, `''` or `[]` clears it; a content-item or product property takes a list of ids. */
+    value: unknown;
+}
+/** A product page's whole change, for {@link ProductsModule.save}. */
+export interface SaveProductInput {
+    id: string;
+    /** The editing language: names, slugs, descriptions and text values are written in it. */
+    languageCode: LanguageCode;
+    product?: SaveProductFieldsInput;
+    variants?: SaveProductVariantInput[];
+    /** The collections the product is in by hand: the whole wanted list. */
+    collectionIds?: string[];
+    /**
+     * The collections the caller last read the product in: only the difference is applied, so a
+     * change someone else made meanwhile stands (as `setCollections`' `from`). Needs `collectionIds`.
+     */
+    fromCollectionIds?: string[];
+    /** An absent property keeps its value. */
+    propertyValues?: SaveProductPropertyValueInput[];
+}
+/**
+ * Something a save did not do although everything it wrote is saved. A string on the wire: a
+ * newer engine may add a code.
+ * - `CONTENT_LABELS_NOT_SYNCED`: the content system did not answer, so the filter values of the
+ *   properties in `propertyIds` were saved without their titles; run
+ *   `catalog.syncContentFacets(propertyId)` on them once it is back.
+ */
+export interface SaveProductWarning {
+    code: 'CONTENT_LABELS_NOT_SYNCED' | (string & {});
+    message: string;
+    propertyIds: string[];
+}
+export interface SaveProductResult {
+    /** The product as saved. */
+    product: Product;
+    /** What the collection step did; null when the save changed no collection. */
+    collections: ProductCollectionsResult | null;
+    warnings: SaveProductWarning[];
+}
+/**
+ * Product-level catalog writes. Reading needs `ReadCatalog` (or `ReadProduct`),
+ * creating `CreateCatalog`, updating `UpdateCatalog`, deleting `DeleteCatalog`.
+ *
+ * While an app or API token of the store owns a field group (`admin.tenant.fieldGroupOwners()`),
+ * an update that would change its Product details, or a delete while
+ * any group of the product or its variants is owned, by anyone else is refused `FIELD_GROUP_LOCKED`
+ * (`BusinessRuleError`, 422) and nothing is written; `error.details` names each refused field
+ * (`field` is a JSON pointer into the call, e.g. `/input/0/price`). A value equal to the stored
+ * one passes and is left out of the write. See the README, "Field groups: what an owned group
+ * refuses".
+ */
+export interface ProductsModule {
+    list(options?: ProductListOptions): Promise<Page<Product>>;
+    /** Null for an id this store does not have — the same answer another tenant's product gets. */
+    get(id: string, options?: Call): Promise<Product | null>;
+    create(input: CreateProductInput, options?: Call): Promise<Product>;
+    update(input: UpdateProductInput, options?: Call): Promise<Product>;
+    /**
+     * Soft-deletes the product and its variants. `PRODUCT_NOT_DELETED`
+     * (`ConflictError`) carries the engine's own reason when it refuses.
+     */
+    delete(id: string, options?: Call): Promise<void>;
+    /**
+     * Duplicate a product (the platform's `cloneProduct`): variants, assets,
+     * facet values, prices, option groups, custom fields, properties, documents,
+     * visibility, SEO metadata, manual recommendations and manual collection
+     * membership. The copy is created DISABLED, named "<Name> (copy)", with SKU
+     * "<sku>-copy" (or the next free "<sku>-copy-N") and no stock. Answers the
+     * new product's id.
+     *
+     * Takes no input: the engine's mutation has none.
+     */
+    clone(id: string, options?: Call): Promise<string>;
+    /** Attach an option group; its options then name the product's variants. */
+    addOptionGroup(productId: string, optionGroupId: string, options?: Call): Promise<Product>;
+    /**
+     * Detach an option group. Refused with `PRODUCT_OPTION_IN_USE_ERROR`
+     * (`BusinessRuleError`) — "Cannot remove ProductOptionGroup "{code}" as it is
+     * used by N ProductVariants. Use the `force` argument to remove it anyway" —
+     * unless `force` is set.
+     */
+    removeOptionGroup(productId: string, optionGroupId: string, options?: Call & {
+        force?: boolean;
+    }): Promise<Product>;
+    /**
+     * Stop offering products the store's organization shares with it, in the ACTIVE store only
+     * (multi-region decision 58): they leave its storefront and its carts, while its orders,
+     * returns and invoices keep them; `excludedFromStore` reads true. Excluding an excluded
+     * product changes nothing. All or nothing, audited. Needs `UpdateCatalog` or `UpdateProduct`.
+     * Answers the products as the store sees them; no ids answers none, without a request. An
+     * Admin API mutation: an idempotency key deduplicates nothing.
+     *
+     * Refusals (nothing is written), GraphQL errors mapped by `core`:
+     * - `STORE_EXCLUSION_LOCAL_PRODUCT` → `BusinessRuleError` (422): a product of the store's own
+     *   (or the store is in no organization), which it disables or deletes instead. The message
+     *   says how many of the ids it was.
+     * - `STORE_EXCLUSION_INPUT_INVALID` → `ValidationError` (400): more than
+     *   {@link MAX_STORE_EXCLUSION_PRODUCTS} distinct ids; refused before sending too.
+     * - `ORGANIZATION_WORKSPACE_NOT_A_STORE` → `BusinessRuleError` (422): called in an
+     *   organization's workspace, which sells nothing.
+     * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): an id this store does not hold.
+     */
+    exclude(productIds: string[], options?: Call): Promise<Product[]>;
+    /**
+     * Offer excluded products in the ACTIVE store again. A product it holds and does not exclude
+     * is left as it is. Same permissions, answer and refusals as {@link exclude}, except
+     * `STORE_EXCLUSION_LOCAL_PRODUCT`; `ENTITY_NOT_FOUND` is a product the store neither holds
+     * nor excludes.
+     */
+    include(productIds: string[], options?: Call): Promise<Product[]>;
+    /**
+     * The organization's Availability toggle (spec §7.2.3, decision 79), called with the
+     * organization's WORKSPACE as the tenant: offer workspace products in member stores, or stop
+     * offering them there. Off, under the `all` assortment: excluded from the store (its orders
+     * keep the product). Off, under `selected`: unlinked from a store that never sold or quoted
+     * it, else excluded. On: included again, or assigned to a store that lacks it. All or
+     * nothing, audited; answers what changed, sorted by store and product, and nothing for what
+     * already was so. Needs `ManageOrganization` (an organization admin) or SuperAdmin, and
+     * `UpdateCatalog` in each store named.
+     *
+     * Refusals (nothing is written), GraphQL errors mapped by `core`:
+     * - `ORGANIZATION_AVAILABILITY_INPUT_INVALID` → `ValidationError` (400): no products or no
+     *   stores, more than {@link MAX_AVAILABILITY_PRODUCTS} distinct products or
+     *   {@link MAX_AVAILABILITY_STORES} distinct stores, or `available` not a boolean; refused
+     *   before sending too.
+     * - `ORGANIZATION_ACCESS_DENIED` → `PermissionDeniedError` (403): the tenant is not an
+     *   organization's workspace.
+     * - `CHANNEL_ACCESS_DENIED` → `PermissionDeniedError` (403): a store the caller may not
+     *   change the catalogue of.
+     * - `ORGANIZATION_CATALOG_NOT_SHARED` → `BusinessRuleError` (422): the organization does not
+     *   share its products (`catalog` sharing is off).
+     * - `ORGANIZATION_PRICE_MISSING` → `BusinessRuleError` (422): a store would be offered a
+     *   variant it has no price for in a currency it sells.
+     * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): a product that is not the workspace's, or a
+     *   store that is not a member.
+     */
+    setAvailabilityInStores(input: SetAvailabilityInStoresInput, options?: Call): Promise<OrganizationProductAvailabilityChange[]>;
+    /**
+     * The read behind the organization's Availability toggle (decision 86), called with the
+     * organization's WORKSPACE as the tenant: whether each named member store offers, excludes or
+     * does not hold each named workspace product, one row per product and store, products first,
+     * in the order named (each distinct id once). Each row names the store's own local copy of the
+     * product, if it has one. It answers whether or not the organization shares its products.
+     * Needs `ManageOrganization` (an organization admin) or SuperAdmin, and `ReadCatalog`,
+     * `ReadProduct` or `UpdateCatalog` in each store named. Platform releases before this method
+     * do not have the query and refuse it as `ValidationError` `GRAPHQL_VALIDATION_FAILED` (400),
+     * told apart from a refused input by its code.
+     *
+     * Refusals, GraphQL errors mapped by `core`:
+     * - `ORGANIZATION_AVAILABILITY_INPUT_INVALID` → `ValidationError` (400): no products or no
+     *   stores, or more than {@link MAX_AVAILABILITY_PRODUCTS} distinct products or
+     *   {@link MAX_AVAILABILITY_STORES} distinct stores; refused before sending too.
+     * - `ORGANIZATION_ACCESS_DENIED` → `PermissionDeniedError` (403): the tenant is not an
+     *   organization's workspace.
+     * - `CHANNEL_ACCESS_DENIED` → `PermissionDeniedError` (403): a store the caller may not read
+     *   the catalogue of.
+     * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): a product that is not the workspace's, or a
+     *   store that is not a member.
+     */
+    availabilityInStores(input: AvailabilityInStoresInput, options?: Call): Promise<OrganizationProductStoreAvailability[]>;
+    /**
+     * Make the ACTIVE member store's own copy of a product its organization shares with it, and
+     * stop offering the shared one, in one step (a local copy, or detach; spec §7.2.8). The copy
+     * is a clone created DISABLED (see {@link clone}), priced with the store's current prices,
+     * carrying the store's price-list entries and joined to the store's own collections only. Its
+     * product and variant rows, names, prices and properties are the store's own and no longer
+     * follow the organization's changes; the workspace's option groups, assets and facet values it
+     * still uses do (a workspace rename of an option shows on the copy, and the store cannot
+     * change them: `MANAGED_BY_ORGANIZATION`). Its variants' SKUs end in `-<store code>`
+     * (first free) unless `skus` names them, which are taken as given or refused. The shared
+     * product is excluded from the store when the store sold or quoted it, and always under the
+     * organization's `all` assortment; otherwise it is removed from the store (`original`).
+     *
+     * One transaction, audited. A repeat (a double submit, a retry) never makes a second copy: it
+     * is refused `LOCAL_COPY_ALREADY_EXISTS`, whether the first call excluded the original or
+     * unlinked it (a platform release older than that answers `ENTITY_NOT_FOUND` after an unlink,
+     * the store no longer holding the product). Needs `CreateCatalog` (or `CreateProduct`) AND
+     * `UpdateCatalog` in the store.
+     *
+     * Refusals (nothing is written), GraphQL errors mapped by `core`:
+     * - `LOCAL_COPY_PRODUCT_NOT_SHARED` → `BusinessRuleError` (422): the store's own product, or
+     *   the store is in no organization; clone it instead.
+     * - `LOCAL_COPY_ALREADY_EXISTS` → `ConflictError` (409): the store already has a live copy.
+     * - `LOCAL_COPY_SKU_CONFLICT` → `ConflictError` (409): a SKU named in `skus` is another
+     *   product's in the store. `error.details` names each one, its `field` the SKU's place in
+     *   `skus` (`/skus/<index>/sku`), so a form can mark the inputs (an older platform release
+     *   sends no details; its message names a single SKU and only counts several).
+     * - `LOCAL_COPY_INPUT_INVALID` → `ValidationError` (400): `skus` names a variant the store
+     *   does not hold on that product, names one twice, repeats a SKU, or has a blank or overlong
+     *   one.
+     * - `ORGANIZATION_WORKSPACE_NOT_A_STORE` → `BusinessRuleError` (422): called in the workspace.
+     * - `FORBIDDEN` → `PermissionDeniedError` (403): a permission above is missing.
+     * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): a product this store does not hold.
+     */
+    makeLocalCopy(productId: string, options?: Call & {
+        skus?: readonly LocalCopySkuInput[];
+    }): Promise<LocalCopyResult>;
+    /**
+     * Set the collections a product is in by hand (headless spec §7, part of `products.save`).
+     * Only MANUAL membership is written: the product is added to the hand-picked list (the
+     * `product-id-filter`, see `catalog.collections`) of each collection in `collectionIds` it is not
+     * in yet, and taken off the hand-picked lists of each collection it should leave. A collection
+     * the product is in only through its other filters (facet values, names) is never rewritten:
+     * those filters are the collection's, so it is reported in `notRemoved`
+     * (`MEMBER_BY_FILTER`) and stays.
+     *
+     * One transaction, and every collection it writes is row-locked first: two calls touching one
+     * collection (two products saved into it at once, a clone) both keep their change, which a
+     * client read-modify-write of the collection's filters (`catalog.collections.update`) cannot
+     * promise. All or nothing. Membership is DERIVED: each written collection re-runs its
+     * membership job, so the product shows in (or out of) it shortly after the call returns, not
+     * during it.
+     *
+     * `from`: where the product was, as far as this call is concerned. Given, only the difference
+     * between `from` and `collectionIds` is applied, and every collection in neither list (or in
+     * both) is left as it is. So a change needs no read: `setCollections(id, [x], { from: [] })`
+     * puts the product in `x` and touches nothing else, and `setCollections(id, [], { from: [x] })`
+     * takes it out of `x` only. A screen that shows the product's collections passes the ones it
+     * loaded, so a collection someone else changed since then keeps that change. Without `from`,
+     * `collectionIds` is the WHOLE new hand-picked membership, compared with the product's
+     * membership now: every other collection that lists the product by hand loses it. A repeat of
+     * a call that went through writes nothing: each collection answers `unchanged`, except one the
+     * product stays in through other filters, which answers `notRemoved` again (while those filters
+     * hold it, and, for a collection with such filters, until its membership job has run). So
+     * `notRemoved` on a repeat does not mean the first call failed.
+     *
+     * Needs `UpdateCatalog` or `UpdateCollection`. Platform releases before this method do not
+     * have the mutation and refuse it as `ValidationError` `GRAPHQL_VALIDATION_FAILED` (400).
+     *
+     * Refusals (nothing is written), GraphQL errors mapped by `core`:
+     * - `PRODUCT_COLLECTIONS_INPUT_INVALID` → `ValidationError` (400): a list names a collection
+     *   twice, or more than {@link MAX_PRODUCT_COLLECTION_IDS}; refused before sending too.
+     *   `error.details` names each entry (`/collectionIds/<i>`, `/fromCollectionIds/<i>`).
+     * - `PRODUCT_COLLECTION_FILTER_INVALID` → `ValidationError` (400): a collection's hand-picked
+     *   list cannot be read as product ids, so whether it names the product cannot be told. The
+     *   message names the collection; save its product list again in the collection editor.
+     * - `SHARED_COLLECTION_NOT_ALLOWED` → `PermissionDeniedError` (403): a collection to write is
+     *   also another store's (or one below it is), and you cannot change that store's catalogue.
+     * - `MANAGED_BY_ORGANIZATION` → `BusinessRuleError` (422): a collection to write is the store's
+     *   organization's; change it in the organization's workspace.
+     * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): a product or collection this store does not
+     *   hold (or a deleted product).
+     * - `FORBIDDEN` → `PermissionDeniedError` (403): neither permission above.
+     */
+    setCollections(productId: string, collectionIds: readonly string[], options?: Call & {
+        from?: readonly string[];
+    }): Promise<ProductCollectionsResult>;
+    /**
+     * Save a product page's whole change in ONE engine transaction: all of it, or none of it
+     * (headless spec §7 `products.save`). In this order: the variants, the hand-picked collections
+     * (as {@link setCollections}), the property values (and the filter-label sync of each
+     * filterable product property), the product. Every step's check runs before the first write.
+     *
+     * A PATCH with an echo rule: only what the input names is compared, and only what differs from
+     * what the store holds is written. A head may send the whole form: an unchanged value is not a
+     * write, so it never records a change of its field group, and a product the store's
+     * organization shares is not refused for a shared field sent back unchanged.
+     *
+     * Labels of content-item values are read from the content system before the transaction. When
+     * it does not answer, the save still goes through and `warnings` names the properties whose
+     * filter values were saved without their titles.
+     *
+     * Needs `UpdateCatalog` or `UpdateProduct`, plus `UpdateCatalog` or `UpdateCollection` when it
+     * changes collections and `UpdateCatalog` when it changes property values. `idempotencyKey`: a
+     * repeat answers the first call's result. Platform releases before this method do not have the
+     * mutation and refuse it as `ValidationError` `GRAPHQL_VALIDATION_FAILED` (400): deploy the
+     * engine first.
+     *
+     * Refusals (nothing is written), GraphQL errors mapped by `core`:
+     * - `PRICE_BASIS_REQUIRED` / `PRICE_BASIS_MISMATCH` / `INVALID_PRICE` → `ValidationError`
+     *   (400): a variant price without the store's basis; refused before sending.
+     * - `PRODUCT_SAVE_INPUT_INVALID` → `ValidationError` (400): the input names nothing, names a
+     *   variant, currency or property value twice, uses a language the store does not offer, gives
+     *   a value outside its field's range, or `price` and the default-currency entry of `prices`
+     *   differ. `error.details` names each (`field` is a pointer into the call).
+     * - `PRODUCT_COLLECTIONS_INPUT_INVALID` → `ValidationError` (400): a collection list names one
+     *   twice, or more than {@link MAX_PRODUCT_COLLECTION_IDS}; refused before sending too.
+     * - `FEED_IDENTIFIER_INVALID` → `ValidationError` (400): a new or changed brand over 70
+     *   characters, or a GTIN of another shape.
+     * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): a product, variant (of another product
+     *   included), collection or property this store does not hold.
+     * - `FORBIDDEN` → `PermissionDeniedError` (403): a step's permission above is missing.
+     * - `SHARED_PRODUCT_NOT_ALLOWED`, `SHARED_PRODUCT_VARIANT_NOT_ALLOWED`,
+     *   `SHARED_COLLECTION_NOT_ALLOWED` → `PermissionDeniedError` (403): a row another store also
+     *   holds, which you cannot change there.
+     * - `MANAGED_BY_ORGANIZATION` → `BusinessRuleError` (422): a CHANGED field of a product, variant,
+     *   collection or property value the store's organization holds. The store's own price, its own
+     *   facet values, its own collections and its own property values pass.
+     * - `FIELD_GROUP_LOCKED` → `BusinessRuleError` (422): a field group an app or API token owns.
+     * - `PRODUCT_COLLECTION_FILTER_INVALID` → `ValidationError` (400): a collection whose
+     *   hand-picked list cannot be read.
+     * - `EXTERNAL_LINE_CARRIER_PROTECTED` → `BusinessRuleError` (422): the platform's carrier.
+     * - `INVALID_TAX_CATEGORY_FOR_CLASS` → `ValidationError` (400).
+     */
+    save(input: SaveProductInput, options?: Call): Promise<SaveProductResult>;
+    /**
+     * Enable, disable, delete or clone up to `MAX_BULK_PRODUCTS` (50) products of the store in ONE
+     * call (headless spec §7 `products.bulkClone`; §6.11).
+     *
+     * **The run is a job.** The call answers a receipt (`runId`) as soon as the run is queued;
+     * `handle.wait()` polls it until it ends and resolves with the run, whatever the ending.
+     * `bulkRun(runId)` reads it again later, from any process. Each product's outcome is in
+     * `run.items`, in the order the ids were named: `OK` (with `newId`, the copy, for `CLONE`), or
+     * `FAILED` with the code the single door would have raised.
+     *
+     * **Each product succeeds or fails alone.** Every product goes through its own door
+     * (`update` with `enabled`, `delete`, `clone`) in a transaction of its own, so a refused product
+     * leaves the others done, and a `SUCCEEDED` run can hold `FAILED` items: read them. A product of
+     * another store answers `ENTITY_NOT_FOUND` on its item; a product another store also holds
+     * answers `SHARED_PRODUCT_NOT_ALLOWED` unless you may change that store's catalogue too; a
+     * product the store's organization holds answers `MANAGED_BY_ORGANIZATION` for every caller,
+     * SuperAdmin included; a group an app or API token owns answers `FIELD_GROUP_LOCKED` (a delete
+     * takes every group of the product; `enabled` is in no group); the external-line carrier
+     * answers `EXTERNAL_LINE_CARRIER_PROTECTED`; core declining a delete answers
+     * `PRODUCT_NOT_DELETED`.
+     *
+     * **Idempotency.** `options.idempotencyKey` (minted when omitted): the same key with the same
+     * action and ids answers the SAME run, so a resubmit never clones twice; the same key with
+     * another selection is refused `IDEMPOTENCY_CONFLICT` (409 `ConflictError`). Each product is
+     * keyed within the run as well, so a run the platform has to process again (a worker restart)
+     * answers each product it already did from that record.
+     *
+     * **No dry run.** The refusals that matter are the doors' own, made under the write (the
+     * field-group lock, the shared-product rule), so a rehearsal could answer "ok" for a product the
+     * real run refuses. Each product's outcome is reported when it runs instead.
+     *
+     * Needs the single door's permission for the action: `UpdateCatalog` or `UpdateProduct`
+     * (ENABLE, DISABLE), `DeleteCatalog` or `DeleteProduct` (DELETE), `CreateCatalog` or
+     * `CreateProduct` (CLONE). Reading the run needs `ReadCatalog` or `ReadProduct`. Search is
+     * reindexed for every product written.
+     *
+     * Refusals of the call itself (nothing is queued), GraphQL errors mapped by `core`:
+     * - `BULK_ACTION_INPUT_INVALID` → `ValidationError` (400): no products, more than
+     *   `MAX_BULK_PRODUCTS`, a product named twice, an unknown action; refused before sending
+     *   too. `error.details` names each entry (`/input/productIds/<index>`).
+     * - `BULK_ACTION_NOT_ALLOWED` → `PermissionDeniedError` (403): the action's permission is missing.
+     * - `IDEMPOTENCY_CONFLICT` → `ConflictError` (409): the key was used for another selection.
+     * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): an id that is not an id at all.
+     *
+     * Platform releases before this method do not have the mutation and refuse it as
+     * `ValidationError` `GRAPHQL_VALIDATION_FAILED` (400).
+     */
+    bulk(input: ProductBulkInput, options?: Call): Promise<JobHandle<ProductBulkRun>>;
+    /**
+     * One read of a bulk product run, by the `runId` `bulk()` answered. A run of another store, or
+     * one that does not exist, is `BULK_ACTION_RUN_NOT_FOUND` (`NotFoundError`, 404).
+     */
+    bulkRun(runId: string, options?: Call): Promise<ProductBulkRun>;
+}
+export declare const PRODUCT_FIELDS = "\n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  createdAt\n  updatedAt\n  languageCode\n  name\n  slug\n  description\n  enabled\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  optionGroups {\n    id\n    code\n    name\n    options {\n      id\n      code\n      name\n    }\n  }\n  translations {\n    id\n    languageCode\n    name\n    slug\n    description\n  }\n  excludedFromStore\n  variantList(options: { take: 1 }) {\n    totalItems\n  }\n  customFields {\n    availabilityState\n    availableFrom\n    preorderLimit\n  }\n";
+export declare const PRODUCTS_QUERY = "\n  query CatalogProducts($options: ProductListOptions) {\n    products(options: $options) {\n      items { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  createdAt\n  updatedAt\n  languageCode\n  name\n  slug\n  description\n  enabled\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  optionGroups {\n    id\n    code\n    name\n    options {\n      id\n      code\n      name\n    }\n  }\n  translations {\n    id\n    languageCode\n    name\n    slug\n    description\n  }\n  excludedFromStore\n  variantList(options: { take: 1 }) {\n    totalItems\n  }\n  customFields {\n    availabilityState\n    availableFrom\n    preorderLimit\n  }\n }\n      totalItems\n    }\n  }\n";
+export declare const PRODUCT_QUERY = "\n  query CatalogProduct($id: ID!) {\n    product(id: $id) { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  createdAt\n  updatedAt\n  languageCode\n  name\n  slug\n  description\n  enabled\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  optionGroups {\n    id\n    code\n    name\n    options {\n      id\n      code\n      name\n    }\n  }\n  translations {\n    id\n    languageCode\n    name\n    slug\n    description\n  }\n  excludedFromStore\n  variantList(options: { take: 1 }) {\n    totalItems\n  }\n  customFields {\n    availabilityState\n    availableFrom\n    preorderLimit\n  }\n }\n  }\n";
+export declare const CREATE_PRODUCT_MUTATION = "\n  mutation CatalogCreateProduct($input: CreateProductInput!) {\n    createProduct(input: $input) { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  createdAt\n  updatedAt\n  languageCode\n  name\n  slug\n  description\n  enabled\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  optionGroups {\n    id\n    code\n    name\n    options {\n      id\n      code\n      name\n    }\n  }\n  translations {\n    id\n    languageCode\n    name\n    slug\n    description\n  }\n  excludedFromStore\n  variantList(options: { take: 1 }) {\n    totalItems\n  }\n  customFields {\n    availabilityState\n    availableFrom\n    preorderLimit\n  }\n }\n  }\n";
+export declare const UPDATE_PRODUCT_MUTATION = "\n  mutation CatalogUpdateProduct($input: UpdateProductInput!) {\n    updateProduct(input: $input) { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  createdAt\n  updatedAt\n  languageCode\n  name\n  slug\n  description\n  enabled\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  optionGroups {\n    id\n    code\n    name\n    options {\n      id\n      code\n      name\n    }\n  }\n  translations {\n    id\n    languageCode\n    name\n    slug\n    description\n  }\n  excludedFromStore\n  variantList(options: { take: 1 }) {\n    totalItems\n  }\n  customFields {\n    availabilityState\n    availableFrom\n    preorderLimit\n  }\n }\n  }\n";
+export declare const DELETE_PRODUCT_MUTATION = "\n  mutation CatalogDeleteProduct($id: ID!) {\n    deleteProduct(id: $id) { \n  result\n  message\n }\n  }\n";
+export declare const CLONE_PRODUCT_MUTATION = "\n  mutation CatalogCloneProduct($id: ID!) {\n    cloneProduct(id: $id)\n  }\n";
+export declare const ADD_OPTION_GROUP_MUTATION = "\n  mutation CatalogAddOptionGroup($productId: ID!, $optionGroupId: ID!) {\n    addOptionGroupToProduct(productId: $productId, optionGroupId: $optionGroupId) { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  createdAt\n  updatedAt\n  languageCode\n  name\n  slug\n  description\n  enabled\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  optionGroups {\n    id\n    code\n    name\n    options {\n      id\n      code\n      name\n    }\n  }\n  translations {\n    id\n    languageCode\n    name\n    slug\n    description\n  }\n  excludedFromStore\n  variantList(options: { take: 1 }) {\n    totalItems\n  }\n  customFields {\n    availabilityState\n    availableFrom\n    preorderLimit\n  }\n }\n  }\n";
+export declare const REMOVE_OPTION_GROUP_MUTATION = "\n  mutation CatalogRemoveOptionGroup($productId: ID!, $optionGroupId: ID!, $force: Boolean) {\n    removeOptionGroupFromProduct(productId: $productId, optionGroupId: $optionGroupId, force: $force) {\n      ... on Product { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  createdAt\n  updatedAt\n  languageCode\n  name\n  slug\n  description\n  enabled\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  optionGroups {\n    id\n    code\n    name\n    options {\n      id\n      code\n      name\n    }\n  }\n  translations {\n    id\n    languageCode\n    name\n    slug\n    description\n  }\n  excludedFromStore\n  variantList(options: { take: 1 }) {\n    totalItems\n  }\n  customFields {\n    availabilityState\n    availableFrom\n    preorderLimit\n  }\n }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
+export declare const EXCLUDE_PRODUCTS_FROM_STORE_MUTATION = "\n  mutation CatalogExcludeProductsFromStore($productIds: [ID!]!) {\n    excludeProductsFromStore(productIds: $productIds) { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  createdAt\n  updatedAt\n  languageCode\n  name\n  slug\n  description\n  enabled\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  optionGroups {\n    id\n    code\n    name\n    options {\n      id\n      code\n      name\n    }\n  }\n  translations {\n    id\n    languageCode\n    name\n    slug\n    description\n  }\n  excludedFromStore\n  variantList(options: { take: 1 }) {\n    totalItems\n  }\n  customFields {\n    availabilityState\n    availableFrom\n    preorderLimit\n  }\n }\n  }\n";
+export declare const INCLUDE_PRODUCTS_IN_STORE_MUTATION = "\n  mutation CatalogIncludeProductsInStore($productIds: [ID!]!) {\n    includeProductsInStore(productIds: $productIds) { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  createdAt\n  updatedAt\n  languageCode\n  name\n  slug\n  description\n  enabled\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  optionGroups {\n    id\n    code\n    name\n    options {\n      id\n      code\n      name\n    }\n  }\n  translations {\n    id\n    languageCode\n    name\n    slug\n    description\n  }\n  excludedFromStore\n  variantList(options: { take: 1 }) {\n    totalItems\n  }\n  customFields {\n    availabilityState\n    availableFrom\n    preorderLimit\n  }\n }\n  }\n";
+export declare const SET_ORGANIZATION_PRODUCT_AVAILABILITY_MUTATION = "\n  mutation CatalogSetOrganizationProductAvailability(\n    $productIds: [ID!]!\n    $channelIds: [ID!]!\n    $available: Boolean!\n  ) {\n    setOrganizationProductAvailability(\n      productIds: $productIds\n      channelIds: $channelIds\n      available: $available\n    ) {\n      productId\n      channelId\n      action\n    }\n  }\n";
+export declare const ORGANIZATION_PRODUCT_AVAILABILITY_QUERY = "\n  query CatalogOrganizationProductAvailability($productIds: [ID!]!, $channelIds: [ID!]!) {\n    organizationProductAvailability(productIds: $productIds, channelIds: $channelIds) {\n      productId\n      channelId\n      state\n      localCopyId\n    }\n  }\n";
+export declare const MAKE_LOCAL_COPY_MUTATION = "\n  mutation CatalogMakeLocalCopy($productId: ID!, $skus: [LocalCopySkuInput!]) {\n    makeLocalCopy(productId: $productId, skus: $skus) {\n      product { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  createdAt\n  updatedAt\n  languageCode\n  name\n  slug\n  description\n  enabled\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  optionGroups {\n    id\n    code\n    name\n    options {\n      id\n      code\n      name\n    }\n  }\n  translations {\n    id\n    languageCode\n    name\n    slug\n    description\n  }\n  excludedFromStore\n  variantList(options: { take: 1 }) {\n    totalItems\n  }\n  customFields {\n    availabilityState\n    availableFrom\n    preorderLimit\n  }\n }\n      originalProductId\n      original\n      droppedOrganizationPropertyCount\n    }\n  }\n";
+export declare const SET_PRODUCT_COLLECTIONS_MUTATION = "\n  mutation CatalogSetProductCollections(\n    $productId: ID!\n    $collectionIds: [ID!]!\n    $fromCollectionIds: [ID!]\n  ) {\n    setProductCollections(\n      productId: $productId\n      collectionIds: $collectionIds\n      fromCollectionIds: $fromCollectionIds\n    ) {\n      added\n      removed\n      unchanged\n      notRemoved {\n        collectionId\n        reason\n      }\n    }\n  }\n";
+export declare const SAVE_PRODUCT_MUTATION = "\n  mutation CatalogSaveProduct($input: SaveProductInput!, $idempotencyKey: String) {\n    saveProduct(input: $input, idempotencyKey: $idempotencyKey) {\n      product { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  createdAt\n  updatedAt\n  languageCode\n  name\n  slug\n  description\n  enabled\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  optionGroups {\n    id\n    code\n    name\n    options {\n      id\n      code\n      name\n    }\n  }\n  translations {\n    id\n    languageCode\n    name\n    slug\n    description\n  }\n  excludedFromStore\n  variantList(options: { take: 1 }) {\n    totalItems\n  }\n  customFields {\n    availabilityState\n    availableFrom\n    preorderLimit\n  }\n }\n      collections {\n        added\n        removed\n        unchanged\n        notRemoved {\n          collectionId\n          reason\n        }\n      }\n      warnings {\n        code\n        message\n        propertyIds\n      }\n    }\n  }\n";
+/** The product as the Admin API answers it, before `toProduct`. */
+export interface WireProduct extends Omit<Product, keyof Availability<string> | 'variantCount'> {
+    variantList: {
+        totalItems: number;
+    };
+    customFields: Partial<Availability<ProductAvailabilityState>> | null;
+}
+/**
+ * Lift the availability custom fields to first-class fields. A server older
+ * than the pre-order engine has no such fields and would refuse the document
+ * outright, so the defaults below only cover a NULL value, never an absent one.
+ */
+export declare function toProduct(wire: WireProduct): Product;
+export declare function productFilter(filter: ProductListFilter | undefined): Record<string, unknown>;
+export declare function createProductsModule(transport: Transport): ProductsModule;