@sixtyninecommerce/admin 0.8.0 → 0.9.0

package/dist/catalog/variants.d.ts

@@ -0,0 +1,274 @@
+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';
+export interface StockLevel {
+    stockLocationId: string;
+    stockOnHand: number;
+    stockAllocated: number;
+}
+export interface StockLevelInput {
+    stockLocationId: string;
+    /** Absolute, not a delta. Refused below zero by the engine ("stockOnHand cannot be a negative value"). */
+    stockOnHand: number;
+}
+export type InventoryFlag = 'TRUE' | 'FALSE' | 'INHERIT';
+/**
+ * How a variant takes parcel space (ADR 2026-09-17 parcel-count rule):
+ * `shared` packs with the rest of the order up to the items per parcel,
+ * `separate` never shares a parcel with other items (one unit per parcel unless
+ * `parcelCapacity` is set), `none` never adds one.
+ */
+export type ParcelPacking = 'shared' | 'separate' | 'none';
+/**
+ * A product variant — the thing that has a SKU, a price and stock.
+ *
+ * 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.
+ */
+export interface ProductVariant extends Availability<VariantAvailabilityState> {
+    id: string;
+    productId: string;
+    createdAt: string;
+    updatedAt: string;
+    languageCode: LanguageCode;
+    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;
+    taxCategory: {
+        id: string;
+        name: string;
+    };
+    /**
+     * The store's tax class this variant belongs to (spec §8.6), or null. When
+     * set, `taxCategory` is the category that class meant for the store's own
+     * country at the moment the variant was last written with it — editing the
+     * class's mappings later does not re-price it.
+     *
+     * A write that sets `taxCategoryId` WITHOUT naming the key (the dashboard's
+     * variant form does this) to a category the class does not mean DETACHES the
+     * class: the key is cleared in the same write, and this reads null.
+     */
+    taxClassKey: string | null;
+    trackInventory: InventoryFlag;
+    outOfStockThreshold: number;
+    useGlobalOutOfStockThreshold: boolean;
+    /**
+     * Units of this variant that fill one parcel. Null uses the store's items per parcel, or 1
+     * when `parcelPacking` is `separate`.
+     */
+    parcelCapacity: number | null;
+    /** Never null on read: an unset packing is `shared`, the engine's default. */
+    parcelPacking: ParcelPacking;
+    stockLevels: StockLevel[];
+    options: Array<{
+        id: string;
+        code: string;
+        name: string;
+        groupId: string;
+    }>;
+    featuredAsset: AssetRef | null;
+    assets: AssetRef[];
+    facetValues: FacetValueRef[];
+    translations: Array<{
+        id: string;
+        languageCode: LanguageCode;
+        name: string;
+    }>;
+}
+export interface VariantTranslationInput extends TranslationInput {
+    name?: string;
+}
+interface VariantFields extends AvailabilityInput<VariantAvailabilityState> {
+    enabled?: boolean;
+    translations?: VariantTranslationInput[];
+    /** One option from EACH of the product's option groups, and a combination no other variant has. */
+    optionIds?: string[];
+    /**
+     * Integer minor units in the store's default currency, stated on
+     * `priceBasis`. The two travel together: a price without its basis is
+     * refused (`PRICE_BASIS_REQUIRED`), and a basis other than the store's is
+     * refused (`PRICE_BASIS_MISMATCH`) — see {@link PriceBasis}.
+     */
+    price?: number;
+    priceBasis?: PriceBasis;
+    /**
+     * Set the category directly. Mutually exclusive with a `taxClassKey` naming
+     * a different category (`INVALID_TAX_CATEGORY_FOR_CLASS`).
+     */
+    taxCategoryId?: string;
+    /**
+     * The store's tax class (spec §8.6). The engine resolves it for the store's
+     * own business country and writes the resulting `taxCategoryId` in the same
+     * write. Refusals, in the engine's words: `TAX_CLASS_NOT_FOUND`
+     * (`NotFoundError`) — "This store has no tax class with the key "…"." — and
+     * `TAX_CLASS_UNMAPPED` (`ValidationError`) — "The tax class "…" has no tax
+     * category for NL and no "*" fallback. Map it before using it here."
+     *
+     * Null clears the key and leaves the category as it is.
+     */
+    taxClassKey?: string | null;
+    /**
+     * A whole number from 1 to 10,000, or null for the default (the store's items per
+     * parcel, or 1 when `parcelPacking` is `separate`). Anything else is refused before sending (`INVALID_PARCEL_CAPACITY`).
+     */
+    parcelCapacity?: number | null;
+    /**
+     * `shared` and null both store null — the one way "shared" is stored, so a
+     * read never tells them apart. Another value is refused before sending
+     * (`INVALID_PARCEL_PACKING`).
+     */
+    parcelPacking?: ParcelPacking | null;
+    stockLevels?: StockLevelInput[];
+    trackInventory?: InventoryFlag;
+    outOfStockThreshold?: number;
+    useGlobalOutOfStockThreshold?: boolean;
+    featuredAssetId?: string | null;
+    assetIds?: string[];
+    facetValueIds?: string[];
+}
+/**
+ * Where a store's price in one currency comes from (multi-region decision 59):
+ * - `OWN` — a price the store stored itself, or its own change of its organization's price.
+ * - `INHERITED` — the organization's stored price, copied to the store and unchanged since; it
+ *   follows the organization's later changes.
+ * - `CONVERTED` — nothing stored: the storefront converts the store's EUR price at the store's
+ *   exchange rate.
+ *
+ * A string on the wire: a newer engine may answer a source this SDK does not name yet.
+ */
+export type VariantPriceSourceKind = 'OWN' | 'INHERITED' | 'CONVERTED';
+/** One currency the active store sells, and where the variant's price in it comes from. */
+export interface VariantPriceSource {
+    currencyCode: string;
+    /**
+     * 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
+     * stored price and no EUR price or exchange rate to convert from, or a currency the store
+     * marked not for sale.
+     */
+    price: number | null;
+    source: VariantPriceSourceKind | (string & {});
+    /**
+     * The organization's stored price in this currency, on the same basis (an organization and its
+     * stores enter prices the same way). Null when no organization shares the variant with the
+     * store, or the organization stores no price in this currency.
+     */
+    organizationPrice: number | null;
+    /** The organization that shares the variant with the store; null for the store's own variant. */
+    organizationName: string | null;
+}
+/** The engine's bound on one `revertPrice` call (`MAX_REVERT_VARIANTS`). */
+export declare const MAX_REVERT_PRICE_VARIANTS = 500;
+export interface CreateProductVariantInput extends VariantFields {
+    productId: string;
+    sku: string;
+    translations: VariantTranslationInput[];
+}
+/** A PATCH: omitted fields are left alone. */
+export interface UpdateProductVariantInput extends VariantFields {
+    id: string;
+    sku?: string;
+}
+/**
+ * Variant writes. Reading needs `ReadCatalog`, creating `CreateCatalog`,
+ * updating (stock included) `UpdateCatalog`, deleting `DeleteCatalog`.
+ *
+ * Refusals, in the engine's words: `optionIds` that do not name one option per
+ * group — "ProductVariant optionIds must include one optionId from each of the
+ * groups: …" — or repeat another variant's combination — "A ProductVariant with
+ * the selected options already exists: …" — and a negative stock level —
+ * "stockOnHand cannot be a negative value" — all arrive as `ValidationError`
+ * (`USER_INPUT_ERROR`). An id this store does not have is a `NotFoundError`
+ * (`ENTITY_NOT_FOUND`). A product may have ONE variant without options; a
+ * second is refused the same way.
+ *
+ * While an app or API token of the store owns a field group (`admin.tenant.fieldGroupOwners()`),
+ * an update or delete of a variant that would change its Price, Stock or
+ * Product details 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 VariantsModule {
+    list(productId: string, options?: ListOptions): Promise<Page<ProductVariant>>;
+    get(id: string, options?: Call): Promise<ProductVariant | null>;
+    /** All or nothing: the engine creates the batch in one transaction. */
+    create(inputs: CreateProductVariantInput[], options?: Call): Promise<ProductVariant[]>;
+    update(inputs: UpdateProductVariantInput[], options?: Call): Promise<ProductVariant[]>;
+    delete(ids: string[], options?: Call): Promise<void>;
+    /**
+     * Set stock on hand per stock location — absolute values, one update. A
+     * location not named keeps its level. Stock MOVEMENTS with a reason are the
+     * `stock` module's (spec §9.2), not this.
+     */
+    setStockLevels(variantId: string, levels: StockLevelInput[], options?: Call): Promise<ProductVariant>;
+    /**
+     * Where each of the variant's prices in the ACTIVE store comes from: one entry per currency the
+     * store sells, in the store's currency order. A store outside any organization, and a variant
+     * of the store's own, read `OWN` or `CONVERTED` only. Needs `ReadCatalog`. An id this store
+     * does not have is a `NotFoundError` (`VARIANT_NOT_FOUND`).
+     */
+    priceSources(variantId: string, options?: Call): Promise<VariantPriceSource[]>;
+    /**
+     * The active store's prices of variants its organization shares with it become the
+     * organization's stored prices again (`INHERITED`), and follow its later changes. Without
+     * `currencyCodes`: every currency the store sells and the organization prices, bar one the store
+     * marked not for sale and stores no price in (a stored price sells the currency whatever its
+     * mark, so it is reverted); an empty list reverts nothing. Needs `UpdateCatalog` (or
+     * `UpdateProduct`), what a variant price write needs. All or nothing, and audited per variant.
+     * Answers the variants as the store sees them. An Admin API mutation: an idempotency key
+     * deduplicates nothing, and a repeat answers the same prices.
+     *
+     * Refusals (nothing is written), GraphQL errors mapped by `core`:
+     * - `ORGANIZATION_PRICE_LOCAL_VARIANT` → `BusinessRuleError` (422): a variant of the store's
+     *   own, or the organization does not share its catalog.
+     * - `ORGANIZATION_PRICE_MISSING` → `BusinessRuleError` (422): the organization stores no price
+     *   in a currency named (or in any the store sells).
+     * - `ORGANIZATION_PRICE_NOT_REVERTIBLE` → `BusinessRuleError` (422): a named currency the store
+     *   does not sell, or marked not for sale for the variant with no price stored in it.
+     * - `ORGANIZATION_WORKSPACE_NOT_A_STORE` → `BusinessRuleError` (422): called in an
+     *   organization's workspace, whose prices are the organization's own.
+     * - `ORGANIZATION_PRICE_REVERT_INVALID` → `ValidationError` (400): more than
+     *   {@link MAX_REVERT_PRICE_VARIANTS} distinct ids; refused before sending too.
+     * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): an id this store does not have.
+     */
+    revertPrice(variantIds: string[], options?: Call & {
+        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 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";
+/** 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>> & {
+        taxClassKey?: string | null;
+        parcelCapacity?: number | null;
+        parcelPacking?: string | null;
+    }) | null;
+}
+export declare function toVariant(wire: WireVariant): ProductVariant;
+export declare function createVariantsModule(transport: Transport): VariantsModule;
+export {};

package/dist/catalog/variants.js

@@ -0,0 +1,258 @@
+import { NotFoundError, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
+import { ASSET_REF_FIELDS, assertDeleted, availabilityCustomFields, DELETION_FIELDS, FACET_VALUE_REF_FIELDS, fieldOf, vendureListPage, } from './types.js';
+const PARCEL_PACKING_MODES = ['shared', 'separate', 'none'];
+/** The engine's bounds for `parcelCapacity` (shipping-calculator's `MAX_PARCEL_CAPACITY`). */
+const PARCEL_CAPACITY_MIN = 1;
+const PARCEL_CAPACITY_MAX = 10_000;
+/** The engine's bound on one `revertPrice` call (`MAX_REVERT_VARIANTS`). */
+export const MAX_REVERT_PRICE_VARIANTS = 500;
+export const VARIANT_FIELDS = /* GraphQL */ `
+  id
+  productId
+  createdAt
+  updatedAt
+  languageCode
+  name
+  sku
+  enabled
+  price
+  priceWithTax
+  currencyCode
+  taxCategory {
+    id
+    name
+  }
+  trackInventory
+  outOfStockThreshold
+  useGlobalOutOfStockThreshold
+  stockLevels {
+    stockLocationId
+    stockOnHand
+    stockAllocated
+  }
+  options {
+    id
+    code
+    name
+    groupId
+  }
+  featuredAsset { ${ASSET_REF_FIELDS} }
+  assets { ${ASSET_REF_FIELDS} }
+  facetValues { ${FACET_VALUE_REF_FIELDS} }
+  translations {
+    id
+    languageCode
+    name
+  }
+  customFields {
+    taxClassKey
+    availabilityState
+    availableFrom
+    preorderLimit
+    parcelCapacity
+    parcelPacking
+  }
+`;
+export const VARIANTS_QUERY = /* GraphQL */ `
+  query CatalogVariants($productId: ID!, $options: ProductVariantListOptions) {
+    productVariants(productId: $productId, options: $options) {
+      items { ${VARIANT_FIELDS} }
+      totalItems
+    }
+  }
+`;
+export const VARIANT_QUERY = /* GraphQL */ `
+  query CatalogVariant($id: ID!) {
+    productVariant(id: $id) { ${VARIANT_FIELDS} }
+  }
+`;
+export const CREATE_VARIANTS_MUTATION = /* GraphQL */ `
+  mutation CatalogCreateVariants($input: [CreateProductVariantInput!]!) {
+    createProductVariants(input: $input) { ${VARIANT_FIELDS} }
+  }
+`;
+export const UPDATE_VARIANTS_MUTATION = /* GraphQL */ `
+  mutation CatalogUpdateVariants($input: [UpdateProductVariantInput!]!) {
+    updateProductVariants(input: $input) { ${VARIANT_FIELDS} }
+  }
+`;
+export const DELETE_VARIANTS_MUTATION = /* GraphQL */ `
+  mutation CatalogDeleteVariants($ids: [ID!]!) {
+    deleteProductVariants(ids: $ids) { ${DELETION_FIELDS} }
+  }
+`;
+/**
+ * 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 const VARIANT_PRICE_SOURCES_QUERY = /* GraphQL */ `
+  query CatalogVariantPriceSources($id: ID!) {
+    productVariant(id: $id) {
+      id
+      priceSources {
+        currencyCode
+        price
+        source
+        organizationPrice
+        organizationName
+      }
+    }
+  }
+`;
+export const REVERT_TO_ORGANIZATION_PRICE_MUTATION = /* GraphQL */ `
+  mutation CatalogRevertToOrganizationPrice($variantIds: [ID!]!, $currencyCodes: [CurrencyCode!]) {
+    revertToOrganizationPrice(variantIds: $variantIds, currencyCodes: $currencyCodes) { ${VARIANT_FIELDS} }
+  }
+`;
+/** The price basis the store stores, read on the SAME tenant as the write. */
+export const PRICE_BASIS_QUERY = /* GraphQL */ `
+  query CatalogPriceBasis {
+    activeChannel {
+      pricesIncludeTax
+    }
+  }
+`;
+function isParcelPacking(value) {
+    return PARCEL_PACKING_MODES.includes(value);
+}
+export function toVariant(wire) {
+    const { customFields, ...rest } = wire;
+    return {
+        ...rest,
+        taxClassKey: customFields?.taxClassKey ?? null,
+        availabilityState: customFields?.availabilityState ?? 'inherit',
+        availableFrom: customFields?.availableFrom ?? null,
+        preorderLimit: customFields?.preorderLimit ?? null,
+        parcelCapacity: customFields?.parcelCapacity ?? null,
+        parcelPacking: isParcelPacking(customFields?.parcelPacking)
+            ? customFields.parcelPacking
+            : 'shared',
+    };
+}
+/** Refuse a parcel rule the engine would refuse, before anything is sent. */
+function assertParcelRule(input) {
+    const { parcelCapacity, parcelPacking } = input;
+    if (parcelCapacity !== undefined &&
+        parcelCapacity !== null &&
+        !(Number.isInteger(parcelCapacity) &&
+            parcelCapacity >= PARCEL_CAPACITY_MIN &&
+            parcelCapacity <= PARCEL_CAPACITY_MAX)) {
+        throw refuse('INVALID_PARCEL_CAPACITY', `parcelCapacity must be a whole number from ${String(PARCEL_CAPACITY_MIN)} to ${String(PARCEL_CAPACITY_MAX)}, or null for the default (the store's items per parcel, or 1 when parcelPacking is separate); got ${JSON.stringify(parcelCapacity)}.`);
+    }
+    if (parcelPacking !== undefined && parcelPacking !== null && !isParcelPacking(parcelPacking)) {
+        throw refuse('INVALID_PARCEL_PACKING', `parcelPacking must be "shared", "separate", "none" or null; got ${JSON.stringify(parcelPacking)}.`);
+    }
+}
+function toWireInput(input) {
+    const { availabilityState, availableFrom, preorderLimit, taxClassKey, parcelCapacity, parcelPacking, priceBasis, ...rest } = input;
+    void priceBasis;
+    const customFields = availabilityCustomFields({
+        availabilityState,
+        availableFrom,
+        preorderLimit,
+    });
+    if (taxClassKey !== undefined)
+        customFields.taxClassKey = taxClassKey;
+    if (parcelCapacity !== undefined)
+        customFields.parcelCapacity = parcelCapacity;
+    if (parcelPacking !== undefined) {
+        customFields.parcelPacking = parcelPacking === 'shared' ? null : parcelPacking;
+    }
+    return Object.keys(customFields).length > 0 ? { ...rest, customFields } : rest;
+}
+function refuse(code, message) {
+    return new ValidationError({ code, message, status: 400, service: 'vendure' });
+}
+export function createVariantsModule(transport) {
+    /**
+     * Every priced input must 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.
+     */
+    const assertPriceBasis = async (inputs, options) => {
+        const priced = inputs.filter((input) => input.price !== undefined);
+        if (priced.length === 0)
+            return;
+        for (const input of priced) {
+            if (!Number.isInteger(input.price)) {
+                throw refuse('INVALID_PRICE', `price must be a whole number of minor units; got ${String(input.price)}.`);
+            }
+            if (input.priceBasis !== 'net' && input.priceBasis !== 'gross') {
+                throw refuse('PRICE_BASIS_REQUIRED', 'A variant price must state its basis: priceBasis "net" or "gross".');
+            }
+        }
+        const channel = await fieldOf(transport, PRICE_BASIS_QUERY, 'activeChannel', {}, options);
+        const storeBasis = channel.pricesIncludeTax ? 'gross' : 'net';
+        const wrong = priced.find((input) => input.priceBasis !== storeBasis);
+        if (wrong) {
+            throw refuse('PRICE_BASIS_MISMATCH', `This store states prices ${storeBasis === 'gross' ? 'including' : 'excluding'} tax, so a price must be sent with priceBasis "${storeBasis}"; got "${String(wrong.priceBasis)}". Convert it before sending — the SDK does not, because the rate depends on each order's zone.`);
+        }
+    };
+    const mapAll = (rows, what) => rows.map((row) => {
+        if (row === null) {
+            // `[ProductVariant]!` allows a null item; a write that answers one has
+            // lost track of a row it just wrote, and pretending otherwise would
+            // hand the caller fewer variants than it sent.
+            throw new UpstreamError({
+                code: 'VARIANT_WRITE_UNCONFIRMED',
+                message: `The engine answered ${what} without one of the variants it wrote. Read them back with variants.list(productId) before retrying.`,
+                status: 502,
+                service: 'vendure',
+            });
+        }
+        return toVariant(row);
+    });
+    const update = async (inputs, options) => {
+        inputs.forEach(assertParcelRule);
+        await assertPriceBasis(inputs, options);
+        const rows = await fieldOf(transport, UPDATE_VARIANTS_MUTATION, 'updateProductVariants', { input: inputs.map((input) => toWireInput({ ...input })) }, options);
+        return mapAll(rows, 'updateProductVariants');
+    };
+    return {
+        list(productId, options) {
+            return vendureListPage(transport, VARIANTS_QUERY, 'productVariants', (skip, take) => ({ productId, options: { skip, take } }), options, toVariant);
+        },
+        async get(id, options) {
+            const variant = await fieldOf(transport, VARIANT_QUERY, 'productVariant', { id }, options);
+            return variant ? toVariant(variant) : null;
+        },
+        async create(inputs, options) {
+            inputs.forEach(assertParcelRule);
+            await assertPriceBasis(inputs, options);
+            const rows = await fieldOf(transport, CREATE_VARIANTS_MUTATION, 'createProductVariants', { input: inputs.map((input) => toWireInput({ ...input })) }, options);
+            return mapAll(rows, 'createProductVariants');
+        },
+        update,
+        async delete(ids, options) {
+            assertDeleted('VARIANT_NOT_DELETED', await fieldOf(transport, DELETE_VARIANTS_MUTATION, 'deleteProductVariants', { ids }, options));
+        },
+        async setStockLevels(variantId, levels, options) {
+            const [variant] = await update([{ id: variantId, stockLevels: levels }], options);
+            return variant;
+        },
+        async priceSources(variantId, options) {
+            const variant = await fieldOf(transport, VARIANT_PRICE_SOURCES_QUERY, 'productVariant', { id: variantId }, options);
+            if (!variant) {
+                throw new NotFoundError({
+                    code: 'VARIANT_NOT_FOUND',
+                    message: `This store has no variant ${variantId}.`,
+                    status: 404,
+                    service: 'vendure',
+                });
+            }
+            return variant.priceSources;
+        },
+        async revertPrice(variantIds, options) {
+            const { currencyCodes, ...call } = options ?? {};
+            // The engine counts distinct ids the way it stores them (lower case).
+            const distinct = new Set(variantIds.map((id) => id.toLowerCase())).size;
+            if (distinct > MAX_REVERT_PRICE_VARIANTS) {
+                throw refuse('ORGANIZATION_PRICE_REVERT_INVALID', `Revert at most ${String(MAX_REVERT_PRICE_VARIANTS)} variants per call; this one named ${String(distinct)}. Nothing was sent.`);
+            }
+            if (variantIds.length === 0)
+                return [];
+            const rows = await fieldOf(transport, REVERT_TO_ORGANIZATION_PRICE_MUTATION, 'revertToOrganizationPrice', { variantIds, currencyCodes: currencyCodes === undefined ? null : [...currencyCodes] }, call);
+            return mapAll(rows, 'revertToOrganizationPrice');
+        },
+    };
+}

package/dist/catalog/visibility.d.ts

@@ -0,0 +1,57 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+export type ProductVisibilityMode = 'public' | 'private';
+/**
+ * Who a product is shown to on the storefront. A product with no row is
+ * public; `private` limits it to the listed customer groups (none listed: to
+ * nobody). Enforced on the Shop API's product, product list and search
+ * resolvers — the Admin API always sees every product.
+ */
+export interface ProductVisibility {
+    productId: string;
+    mode: ProductVisibilityMode;
+    /** `manual` for anything written here; `imported` for rows the import pipeline wrote. */
+    source: 'manual' | 'imported';
+    allowedCustomerGroupIds: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SetProductVisibilityInput {
+    productId: string;
+    mode: ProductVisibilityMode;
+    /** Ignored under `public`. */
+    allowedCustomerGroupIds?: string[];
+}
+/**
+ * Per-product storefront visibility. Needs `ReadCatalog` / `UpdateCatalog`.
+ *
+ * `set` on a product of another store is refused with the engine's
+ * `USER_INPUT_ERROR` (`ValidationError`): "Product {id} not found in this
+ * channel". A write from here is always `source: manual`, which a later
+ * pipeline import leaves alone.
+ *
+ * The Admin API's `productsByVisibility` list is deliberately NOT exposed: it
+ * counts and pages visibility rows across every store before narrowing to this
+ * one, so its totals and pages are wrong (recorded as a finding).
+ */
+export interface VisibilityModule {
+    /** Null when the product has no override (it is public). `NotFoundError` for an unknown product. */
+    get(productId: string, options?: Call): Promise<ProductVisibility | null>;
+    set(input: SetProductVisibilityInput, options?: Call): Promise<ProductVisibility>;
+    /** Apply one setting to many products; answers how many rows changed. */
+    bulkSet(input: {
+        productIds: string[];
+        mode: ProductVisibilityMode;
+        allowedCustomerGroupIds?: string[];
+    }, options?: Call): Promise<number>;
+    /**
+     * Remove the override (the product becomes public). Resolves the same way
+     * whether or not there was one: the engine does not say.
+     */
+    clear(productId: string, options?: Call): Promise<void>;
+}
+export declare const PRODUCT_VISIBILITY_QUERY = "\n  query CatalogProductVisibility($id: ID!) {\n    product(id: $id) {\n      id\n      visibility { \n  productId\n  mode\n  source\n  allowedCustomerGroupIds\n  createdAt\n  updatedAt\n }\n    }\n  }\n";
+export declare const SET_VISIBILITY_MUTATION = "\n  mutation CatalogSetVisibility($input: SetProductVisibilityInput!) {\n    setProductVisibility(input: $input) { \n  productId\n  mode\n  source\n  allowedCustomerGroupIds\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const BULK_SET_VISIBILITY_MUTATION = "\n  mutation CatalogBulkSetVisibility($input: BulkSetProductVisibilityInput!) {\n    bulkSetProductVisibility(input: $input) {\n      updated\n    }\n  }\n";
+export declare const CLEAR_VISIBILITY_MUTATION = "\n  mutation CatalogClearVisibility($productId: ID!) {\n    clearProductVisibility(productId: $productId)\n  }\n";
+export declare function createVisibilityModule(transport: Transport): VisibilityModule;

package/dist/catalog/visibility.js

@@ -0,0 +1,59 @@
+import { NotFoundError } from '@sixtyninecommerce/core';
+import { fieldOf } from './types.js';
+const VISIBILITY_FIELDS = /* GraphQL */ `
+  productId
+  mode
+  source
+  allowedCustomerGroupIds
+  createdAt
+  updatedAt
+`;
+export const PRODUCT_VISIBILITY_QUERY = /* GraphQL */ `
+  query CatalogProductVisibility($id: ID!) {
+    product(id: $id) {
+      id
+      visibility { ${VISIBILITY_FIELDS} }
+    }
+  }
+`;
+export const SET_VISIBILITY_MUTATION = /* GraphQL */ `
+  mutation CatalogSetVisibility($input: SetProductVisibilityInput!) {
+    setProductVisibility(input: $input) { ${VISIBILITY_FIELDS} }
+  }
+`;
+export const BULK_SET_VISIBILITY_MUTATION = /* GraphQL */ `
+  mutation CatalogBulkSetVisibility($input: BulkSetProductVisibilityInput!) {
+    bulkSetProductVisibility(input: $input) {
+      updated
+    }
+  }
+`;
+export const CLEAR_VISIBILITY_MUTATION = /* GraphQL */ `
+  mutation CatalogClearVisibility($productId: ID!) {
+    clearProductVisibility(productId: $productId)
+  }
+`;
+export function createVisibilityModule(transport) {
+    return {
+        async get(productId, options) {
+            const product = await fieldOf(transport, PRODUCT_VISIBILITY_QUERY, 'product', { id: productId }, options);
+            if (!product) {
+                throw new NotFoundError({
+                    code: 'PRODUCT_NOT_FOUND',
+                    message: `This store has no product ${productId}.`,
+                    status: 404,
+                    service: 'vendure',
+                });
+            }
+            return product.visibility;
+        },
+        set: (input, options) => fieldOf(transport, SET_VISIBILITY_MUTATION, 'setProductVisibility', { input }, options),
+        async bulkSet(input, options) {
+            const result = await fieldOf(transport, BULK_SET_VISIBILITY_MUTATION, 'bulkSetProductVisibility', { input }, options);
+            return result.updated;
+        },
+        async clear(productId, options) {
+            await fieldOf(transport, CLEAR_VISIBILITY_MUTATION, 'clearProductVisibility', { productId }, options);
+        },
+    };
+}