@sixtyninecommerce/client 0.23.1 → 0.25.0

package/dist/types.d.ts

@@ -1,15 +1,44 @@
+/** Retry configuration for transient GET failures. */
 export interface RetryConfig {
+    /** Maximum number of attempts including the first request. Default: 2. */
     attempts?: number;
+    /** Base delay in ms for exponential backoff. Default: 200. */
     baseDelayMs?: number;
 }
+/**
+ * Per-call request controls. Pass to read methods (catalog, content,
+ * navigation) to cancel in-flight requests — useful for SSR and
+ * search-as-you-type.
+ */
 export interface RequestOptions {
     signal?: AbortSignal;
+    /**
+     * Extra cache tags for this request, added to the SDK's own — e.g.
+     * `getProduct(slug, { cacheTags: [productCacheTag(route.id)] })` when the id
+     * is already known from the route manifest. Applied to commerce (Vendure)
+     * requests only; see {@link StorefrontClientConfig.cacheTags}.
+     */
     cacheTags?: readonly string[];
 }
+/**
+ * Decides the cache tags a commerce request carries. Receives the SDK's
+ * defaults (plus any per-request `cacheTags`) and the SDK method name
+ * (`getProduct`, `getProductById`, `searchProducts`, …); returns what to send.
+ */
 export type CacheTagResolver = (tags: readonly string[], request: {
     readonly operation: string;
 }) => readonly string[];
+/**
+ * Which storefront a cart/order belongs to.
+ *
+ * A tenant can run a consumer shop and a trade (B2B/dealer) shop off ONE
+ * channel. Without a scope both storefronts share a single active order per
+ * customer, because Vendure's fallback lookup is "the one active order for this
+ * customer in this channel" — separate cookies do not change that. Setting a
+ * scope keeps the two carts apart.
+ */
 export type OrderScope = 'CONSUMER' | 'TRADE';
+/** Configuration for creating a storefront client. */
 export interface StorefrontClientConfig {
     storeCode: string;
     cdnUrl: string;
@@ -18,18 +47,96 @@ export interface StorefrontClientConfig {
     pluginsUrl?: string;
     defaultLanguageCode?: string;
     fetch?: typeof globalThis.fetch;
+    /** Called when an auth token is received from Vendure (e.g. after login). Use to persist the token. */
     onAuthToken?: (token: string) => void;
+    /**
+     * Called when the SDK detects the stored session is genuinely dead. Fires on
+     * an UNAUTHORIZED error, and on a FORBIDDEN error only when a follow-up
+     * `activeCustomer` probe confirms there is no active session — Vendure's Shop
+     * API returns FORBIDDEN for both an expired session and a real authorization
+     * denial, so the probe is what tells them apart. Use to prompt re-login or
+     * clear local user state. A FORBIDDEN with a still-valid session is an
+     * authorization denial, NOT an expiry: `onAuthExpired` does not fire and the
+     * caller receives a StorefrontError with `errorCode: 'FORBIDDEN'` /
+     * `statusCode: 403` to handle.
+     */
     onAuthExpired?: () => void;
+    /**
+     * Called after `logout()` clears the stored auth token — the inverse of
+     * `onAuthToken`. Use to drop the persisted token from storage/cookies. NOT
+     * fired on session expiry (that is `onAuthExpired`).
+     */
     onAuthCleared?: () => void;
+    /**
+     * Retry config for transient GET failures (network errors and 502/503/504).
+     * Defaults to `{ attempts: 2, baseDelayMs: 200 }`. Set `attempts: 1` to
+     * disable retries entirely. Mutations are never retried.
+     */
     retry?: RetryConfig;
+    /**
+     * Which storefront this client speaks for — `'CONSUMER'` or `'TRADE'`. Sent
+     * as the `x-order-scope` header on every Vendure Shop API request, which is
+     * what keeps a dealer's consumer basket and trade order separate on a single
+     * channel.
+     *
+     * Leave it unset for a single-storefront tenant: the engine then behaves
+     * exactly as stock Vendure does. Unset is NOT the same as `'CONSUMER'` — a
+     * client that omits the header never has an existing trade cart reclassified.
+     *
+     * A `'TRADE'` cart requires a logged-in customer; the engine rejects an
+     * anonymous trade order with `error.trade-order-requires-authentication`.
+     *
+     * Per client, not per request — run two clients (or call `setOrderScope`) if
+     * one process serves both storefronts.
+     */
     orderScope?: OrderScope;
+    /**
+     * Cache tags on product and collection reads, for Next.js `revalidateTag` —
+     * the tags `createEventRevalidateHandler` purges. The SDK adds
+     * `next: { tags }` to the fetch init (Next reads it; other fetch
+     * implementations ignore unknown init keys) and sets no cache policy:
+     * whether a request is cached stays your app's decision.
+     *
+     * - `true` (default): tags derived from each call's inputs — `product:<id>`
+     *   for `getProductById` and `getProductProperties`, `collection:<id>` for
+     *   `getCollectionById`, `getProductsInCollectionById` and `searchProducts`
+     *   with `collectionId`/`collectionIds`.
+     * - `false`: no `next` key on any request.
+     * - a {@link CacheTagResolver}: decides per request.
+     *
+     * Load pages by the id `findRoute` resolves and they are tagged. Raw slug
+     * reads (`getProduct(slug)`, `getCollection(slug)`,
+     * `getProductsInCollection(slug)`) stay untagged — the id is not known until
+     * the response arrives; pass `route.cacheTags` per request to tag one.
+     */
     cacheTags?: boolean | CacheTagResolver;
 }
+/**
+ * Storefront-visible Channel custom fields. Enumerates fields the SDK or its
+ * consumers read directly. Unknown fields are still accessible via the index
+ * signature, so adding a new field on the backend doesn't require an SDK
+ * release for storefronts to consume it.
+ */
 export interface ChannelCustomFields {
+    /** SDK consumes this to gate the entire client into read-only mode. */
     maintenanceMode?: boolean;
+    /** Custom CDN domain for asset URLs (set per-channel via cdn-domain plugin). */
     cdnDomain?: string | null;
+    /**
+     * Absolute URL of the storefront for this channel (e.g. `https://store.example.com`).
+     * Required by the SEO module to emit canonical URLs and hreflang tags.
+     */
     storefrontUrl?: string;
+    /**
+     * URL strategy the storefront uses to encode the active language. Drives
+     * canonical/alternate URL generation in the SEO module.
+     */
     urlLocaleStrategy?: 'path-prefix' | 'subdomain' | 'none';
+    /**
+     * When `true`, the URL still includes a locale prefix even for the channel's
+     * default language. When `false` (default), the default language URL has no
+     * prefix.
+     */
     urlLocalePrefixDefault?: boolean;
     businessName?: string | null;
     businessDescription?: string | null;
@@ -50,19 +157,50 @@ export interface ChannelCustomFields {
     postalCode?: string | null;
     province?: string | null;
     country?: string | null;
+    /** JSON-encoded social URLs map. Keys: facebook, instagram, twitter, linkedin, youtube, tiktok. */
     socialLinks?: string | null;
     commercePathPrefix?: string | null;
+    /** JSON-encoded `{ [languageCode]: pathPrefix }` per-locale overrides. */
     commercePathPrefixTranslations?: string | null;
+    /** Segment canonical product URLs sit under. Unset/empty means `products`. */
     productPathSegment?: string | null;
+    /** Channel default Twitter / X handle (without @). Used by `metaTagsFor()` for `twitter:site`. */
     twitterHandle?: string | null;
+    /** Vendure Asset ID used as the fallback OpenGraph image when a product does not provide one. */
     defaultOgImageId?: string | null;
+    /** When true, the storefront serves `/llms.txt` advertising AI-friendly endpoints. */
     llmsTxtEnabled?: boolean;
+    /**
+     * When true, B2B customers can submit quote requests on this channel.
+     * Storefronts should gate quote UI (request-quote buttons, "My quotes"
+     * account section) on this flag instead of probing `createQuoteRequest`.
+     */
     quotesEnabled?: boolean;
+    /**
+     * When true, customers can request order returns on this channel.
+     * Storefronts should gate return UI ("Request return" buttons, "My
+     * returns" account section) on this flag instead of probing
+     * `requestReturn`.
+     */
     returnsEnabled?: boolean;
+    /** Days after delivery/shipment during which a return may be requested. */
     returnWindowDays?: number;
+    /**
+     * Channel-wide display default: `channel` (follow `pricesIncludeTax`),
+     * `gross` or `net`. Raw storage value — read it with `parseTaxDisplayPolicy`
+     * and render from `pricing.getTaxDisplayMode()`, which resolves the whole
+     * policy server-side for the actual shopper.
+     */
     taxDisplayDefault?: string | null;
+    /** B2B override: `inherit`, `gross` or `net`. See {@link taxDisplayDefault}. */
     taxDisplayB2b?: string | null;
+    /**
+     * JSON array of ISO-3166 alpha-2 codes, e.g. `["US"]`. A shopper whose
+     * country is listed always sees prices excl. tax AND is taxed by their own
+     * country's tax zone. Empty/unset = the rule is off.
+     */
     taxExclusiveCountries?: string | null;
+    /** Forward-compat: any additional storefront-visible custom fields. */
     [key: string]: unknown;
 }
 export interface BrandingAssetRef {
@@ -77,6 +215,7 @@ export interface BrandingFontResource {
     kind: 'google' | 'self_hosted';
     family: string;
     weights: number[];
+    /** Resolved Asset references for self-hosted fonts. Empty for Google Fonts. */
     files: BrandingAssetRef[];
 }
 export interface BrandingSocialLinks {
@@ -120,6 +259,11 @@ export interface BrandingLegal {
 }
 export interface BrandingStorefrontConfig {
     url: string | null;
+    /**
+     * Resolved CDN base URL. When the channel sets `cdnDomain`, this is
+     * `https://{cdnDomain}`; otherwise it falls back to the global CDN URL the
+     * client was constructed with.
+     */
     cdnUrl: string;
     urlLocaleStrategy: 'path-prefix' | 'subdomain' | 'none';
     urlLocalePrefixDefault: boolean;
@@ -139,15 +283,23 @@ export interface BrandingInfo {
     social: BrandingSocialLinks;
     storefront: BrandingStorefrontConfig;
 }
+/** Channel info resolved from CMS at initialization. */
 export interface ChannelInfo {
     id: string;
     code: string;
     token: string;
     defaultLanguageCode: string;
     defaultCurrencyCode: string;
+    /**
+     * The channel's tax-display storage mode. When `true`, `price`/`*Price`
+     * fields already include tax; when `false`, they are net and the gross
+     * figure lives in the matching `priceWithTax`/`*PriceWithTax` field. Drives
+     * net-vs-gross display decisions (e.g. a B2B/B2C BTW toggle).
+     */
     pricesIncludeTax: boolean;
     customFields: ChannelCustomFields;
 }
+/** Shared context used by all modules. */
 export interface StoreContext {
     channel: ChannelInfo;
     cdnUrl: string;
@@ -157,9 +309,21 @@ export interface StoreContext {
     pluginsUrl: string;
     languageCode: string;
     currencyCode: string;
+    /** Channel tax-display storage mode — see {@link ChannelInfo.pricesIncludeTax}. */
     pricesIncludeTax: boolean;
     authToken: string | null;
+    /**
+     * Active order scope, emitted as the `x-order-scope` header. `null`/absent
+     * means "send no header" — legacy, unscoped behaviour. See
+     * {@link StorefrontClientConfig.orderScope}.
+     */
     orderScope?: OrderScope | null;
+    /**
+     * Last resolved tax display mode, cached against the identity it was resolved
+     * for (see `identityStamp`). Owned by `pricing.getTaxDisplayMode()`; cleared
+     * by `setShippingAddress` because moving the order's country can flip the
+     * mode without changing the identity. Treat as internal.
+     */
     taxDisplay?: ResolvedTaxDisplay | null;
     fetch: typeof globalThis.fetch;
     onAuthToken?: (token: string) => void;
@@ -169,6 +333,7 @@ export interface StoreContext {
         attempts: number;
         baseDelayMs: number;
     };
+    /** See {@link StorefrontClientConfig.cacheTags}. Absent means `true`. */
     cacheTags?: boolean | CacheTagResolver;
 }
 export interface GraphQLResponse<T = unknown> {
@@ -202,7 +367,9 @@ export interface AssetPresets {
 export interface Asset {
     source: string;
     name?: string;
+    /** Intrinsic pixel width of the source image. Absent when not selected. */
     width?: number | null;
+    /** Intrinsic pixel height of the source image. Absent when not selected. */
     height?: number | null;
     customFields?: {
         altText?: string;
@@ -214,6 +381,7 @@ export interface CmsAssetTranslation {
     language_code: string;
     alt_text: string | null;
 }
+/** Public-safe CMS asset returned by /assets/lookup, /public-assets/:id. */
 export interface CmsAsset {
     id: string;
     filename: string;
@@ -265,15 +433,52 @@ export interface ProductVariant {
     priceWithTax: number;
     currencyCode: string;
     stockLevel: string;
+    /**
+     * Physical on-hand stock across the channel's locations. `null` when the
+     * channel does not expose operational stock numbers (the default) — fall
+     * back to the `stockLevel` string.
+     */
     stockOnHand: number | null;
+    /** Stock reserved by open orders. `null` when the channel does not expose it. */
     stockAllocated: number | null;
+    /**
+     * Units a customer can actually order right now (available-to-promise).
+     * `null` when the channel does not expose operational stock numbers.
+     */
     saleable: number | null;
+    /**
+     * Units already on order from suppliers (e.g. open Exact purchase orders).
+     * `null` unless the channel exposes stock AND the signed-in customer's group
+     * may see incoming stock — anonymous visitors always get `null`.
+     */
     incomingStock: number | null;
+    /** Forward-looking `max(0, saleable) + incomingStock`. Same gate as `incomingStock`. */
     projectedSaleable: number | null;
+    /**
+     * Earliest FUTURE expected warehouse arrival, ISO 8601. Never a past date.
+     * `null` under the same gate as `incomingStock`, and ALSO when no open line
+     * has a future date — so `incomingStock > 0` with `nextExpectedArrival: null`
+     * is normal (on order, but every date is overdue or missing). Show a dateless
+     * "restock on order" hint then. This is a warehouse-arrival estimate, never a
+     * delivery promise.
+     */
     nextExpectedArrival: string | null;
+    /**
+     * Units BEYOND `saleable` the signed-in customer may order on backorder right
+     * now. The quantity ceiling is `max(0, saleable) + backorderAllowance` (see
+     * `maxOrderableQuantity` in `@sixtyninecommerce/client/pricing`). `null` when
+     * the question does not apply — anonymous, group may not backorder, or the
+     * channel hides stock — treat exactly like today; `0` = denied; a large
+     * value (2,000,000,000) is the "unlimited" sentinel. A snapshot: the server
+     * re-checks on add-to-cart and at placement and refuses with the usual
+     * `InsufficientStockError` / `INSUFFICIENT_STOCK`, whose `quantityAvailable`
+     * then already includes the allowance.
+     */
+    backorderAllowance: number | null;
     priceListName: string | null;
     retailPrice: number | null;
     retailPriceWithTax: number | null;
+    /** Tax rate applied to this price in the active channel/zone, e.g. `{ value: 21 }` for 21% VAT. */
     taxRateApplied: {
         value: number;
     } | null;
@@ -303,6 +508,14 @@ export interface CollectionRef {
     name: string;
     slug: string;
     position?: number;
+    /**
+     * The parent's `slug` is load-bearing, not decoration: a top-level collection
+     * is parented to the `__root_collection__` SENTINEL (Vendure resolves `parent`
+     * to null only when the real parent is PRIVATE), so the slug is what
+     * distinguishes "this is a root" from "this is nested". The SDK's own product
+     * queries select it. A caller writing its own query and omitting it gets the
+     * flat product path for every canonical — see `isUserFacingRoot`.
+     */
     parent?: {
         id: string;
         slug?: string;
@@ -342,6 +555,7 @@ export interface PublicProductDocument {
     fileMimeType: string;
     fileSize: number;
     fileName: string;
+    /** When true, the URL is presigned and short-lived. Don't cache it. */
     requiresAuth: boolean;
 }
 export interface Product {
@@ -357,6 +571,11 @@ export interface Product {
     collections: CollectionRef[];
     translations?: ProductTranslation[];
     documents?: PublicProductDocument[];
+    /**
+     * Per-product SEO/social/AI metadata. Resolved server-side for the active
+     * language and validated client-side at the SDK boundary. `null` when no
+     * metadata has been authored for this product on the current channel.
+     */
     metadata?: import('./seo/metadata-types.js').ProductMetadata | null;
 }
 export interface RecommendedProductGroup {
@@ -369,6 +588,7 @@ export interface ProductSummary {
     name: string;
     slug: string;
     description?: string;
+    /** Whether the product is enabled on the channel. Selected by `LIST_PRODUCTS`. */
     enabled?: boolean;
     featuredAsset: Asset | null;
     variants: Array<{
@@ -379,12 +599,21 @@ export interface ProductSummary {
         priceWithTax: number;
         currencyCode: string;
         stockLevel: string;
+        /** ATP numbers — `null` when the channel does not expose operational stock. */
         stockOnHand?: number | null;
         stockAllocated?: number | null;
         saleable?: number | null;
+        /**
+         * Incoming-stock numbers — additionally `null` unless the signed-in customer's
+         * group may see incoming stock. `nextExpectedArrival` is the earliest FUTURE
+         * arrival (ISO 8601, never past) and is `null` when every open line is overdue,
+         * even while `incomingStock > 0`.
+         */
         incomingStock?: number | null;
         projectedSaleable?: number | null;
         nextExpectedArrival?: string | null;
+        /** Units beyond `saleable` this buyer may backorder; `null` = not applicable. */
+        backorderAllowance?: number | null;
         availabilityByLocation?: VariantLocationAvailability[];
         priceListName?: string | null;
         retailPrice?: number | null;
@@ -417,6 +646,7 @@ export interface Breadcrumb {
     name: string;
     slug: string;
 }
+/** Per-language translation of a collection, including SEO custom fields. */
 export interface CollectionTranslation {
     languageCode: string;
     name?: string;
@@ -430,6 +660,7 @@ export interface CollectionTranslation {
         socialImageAlt?: string | null;
     } | null;
 }
+/** Collection-scoped custom fields: routing directives + SEO scalars. */
 export interface CollectionCustomFields {
     isRoutable?: boolean | null;
     isCanonical?: boolean | null;
@@ -462,12 +693,21 @@ export interface CollectionDetail extends Collection {
             priceWithTax: number;
             currencyCode: string;
             stockLevel: string;
+            /** ATP numbers — `null` when the channel does not expose operational stock. */
             stockOnHand: number | null;
             stockAllocated: number | null;
             saleable: number | null;
+            /**
+             * Incoming-stock numbers — additionally `null` unless the signed-in customer's
+             * group may see incoming stock. `nextExpectedArrival` is the earliest FUTURE
+             * arrival (ISO 8601, never past) and is `null` when every open line is overdue,
+             * even while `incomingStock > 0`.
+             */
             incomingStock: number | null;
             projectedSaleable: number | null;
             nextExpectedArrival: string | null;
+            /** Units beyond `saleable` this buyer may backorder; `null` = not applicable. */
+            backorderAllowance: number | null;
             priceListName: string | null;
             retailPrice: number | null;
             retailPriceWithTax: number | null;
@@ -485,29 +725,75 @@ export interface CollectionDetail extends Collection {
         totalItems: number;
     };
 }
+/**
+ * Stable, append-only vocabulary for why an order could not be placed — or why
+ * a payment was refused before it was taken.
+ *
+ * Branch on this instead of keyword-matching `transitionError` /
+ * `paymentErrorMessage`: that prose is operator English, is re-worded per
+ * merchant, and is translated. This list is a deliberate copy of the
+ * platform's (`@sixtynine-digital/commerce-shared/placement-rejection`) so the
+ * published client stays zero-dependency; a spec asserts the two match.
+ *
+ * Treat an unrecognised value defensively — always give your `switch` a
+ * `default:` branch and fall back to `MutationError.message`. Codes are added
+ * over time, and the SDK deliberately passes a code it does not know through
+ * unchanged rather than rewriting it to `UNKNOWN`.
+ */
 export type PlacementRejectionCode = 'ORDER_EMPTY' | 'CUSTOMER_REQUIRED' | 'SHIPPING_METHOD_REQUIRED' | 'INSUFFICIENT_STOCK' | 'ORDER_MINIMUM_AMOUNT_NOT_MET' | 'ORDER_MINIMUM_QUANTITY_NOT_MET' | 'FULFILLMENT_MINIMUM_NOT_MET' | 'LINE_MINIMUM_QUANTITY_NOT_MET' | 'LINE_SALES_UNIT_NOT_MET' | 'SHIPPING_ADDRESS_INCOMPLETE' | 'SHIPPING_COUNTRY_NOT_SERVED' | 'AGE_VERIFICATION_REQUIRED' | 'AGE_REQUIREMENT_NOT_MET' | 'DELIVERY_TERMS_UNAVAILABLE' | 'PAYMENT_TERMS_UNAVAILABLE' | 'PAYMENT_INTENT_MISMATCH' | 'PLACEMENT_BLOCKED' | 'UNKNOWN';
+/**
+ * An order line implicated in a rejection — the line below its minimum
+ * quantity, the line that ran short of stock.
+ *
+ * The engine caps a rejection at 20 lines (`PlacementRejection.linesTruncated`
+ * says when it did). Every field except the variant id is nullable, so render
+ * defensively; `productName`/`productVariantName` are already translated.
+ */
 export interface PlacementRejectionLine {
     orderLineId?: string | null;
     productVariantId: string;
     sku?: string | null;
     productVariantName?: string | null;
     productName?: string | null;
+    /** What was asked for, before any correction the engine applied. */
     quantityRequested?: number | null;
     quantityAvailable?: number | null;
 }
+/**
+ * Field-level detail, e.g. which part of the shipping address is unusable.
+ *
+ * Deliberately NOT `FieldError` (the CMS form-validation shape): `field` is
+ * nullable here, because a detail may be about the order as a whole.
+ */
 export interface PlacementRejectionDetail {
     field?: string | null;
     code?: string | null;
     message: string;
 }
+/**
+ * The structured, customer-safe half of a placement rejection.
+ *
+ * `customerMessage` is plain shopper English and safe to render as-is; the
+ * operator prose stays on the error's own reason field for merchant-facing
+ * surfaces. The metadata fields are populated per code (e.g. `requiredAmount` +
+ * `amountBasis` for a minimum-amount rejection) and are null otherwise.
+ */
 export interface PlacementRejection {
+    /**
+     * Widened past the union on purpose: the SDK passes a code it does not know
+     * through unchanged, so an exhaustive `switch` must still have a `default:`.
+     */
     code: PlacementRejectionCode | (string & {});
+    /** Shopper-safe sentence. Null when the veto site supplied none. */
     customerMessage?: string | null;
     lines?: PlacementRejectionLine[] | null;
     details?: PlacementRejectionDetail[] | null;
+    /** True when `lines` was capped and does not list every affected line. */
     linesTruncated: boolean;
+    /** Minor units, in `currencyCode`. */
     requiredAmount?: number | null;
     currencyCode?: string | null;
+    /** `net` or `gross` — which basis `requiredAmount` is expressed in. */
     amountBasis?: string | null;
     requiredQuantity?: number | null;
     priceListName?: string | null;
@@ -516,16 +802,21 @@ export interface PlacementRejection {
 }
 export type AdjustmentType = 'PROMOTION' | 'DISTRIBUTED_ORDER_PROMOTION' | 'OTHER';
 export interface Discount {
+    /** Identifier of the source (e.g. promotion code or shipping method id). */
     adjustmentSource: string;
     type: AdjustmentType | string;
     description: string;
+    /** Pre-tax discount amount in minor units. Negative values reduce the price. */
     amount: number;
     amountWithTax: number;
 }
 export interface OrderTaxSummary {
     description: string;
+    /** Tax rate as a percentage (e.g. 21 for 21%). */
     taxRate: number;
+    /** Net total to which this tax rate applies, in minor units. */
     taxBase: number;
+    /** Tax total at this rate, in minor units. */
     taxTotal: number;
 }
 export interface OrderPromotion {
@@ -537,18 +828,41 @@ export interface OrderPromotion {
 export interface OrderLine {
     id: string;
     quantity: number;
+    /**
+     * Units of this line physical stock did NOT cover when the order was placed
+     * (the part the merchant ships later). Stamped at placement, never
+     * decremented as the line ships — the fulfilments record what arrived.
+     *
+     * Selected by the PLACED-order reads alone (`getOrderByCode`,
+     * `getCustomerOrders`), so it is `undefined` from the cart reads and
+     * mutations: a cart line has no stamp to carry, and selecting it in the
+     * shared fragment would couple every cart call to an engine that has the
+     * field.
+     */
+    backorderedQuantity?: number;
     unitPrice: number;
     unitPriceWithTax: number;
+    /** Tax rate applied to this line as a percentage (e.g. 21 for 21%). */
     taxRate: number;
     linePrice: number;
     linePriceWithTax: number;
+    /** Line price after item-level discounts, excluding tax. */
     discountedLinePrice: number;
     discountedLinePriceWithTax: number;
+    /** Discounts applied to this line (item-level promotions). */
     discounts: Discount[];
     productVariant: {
         id: string;
         name: string;
         sku: string;
+        /**
+         * Units the channel will sell right now, `null` when it hides stock. Here
+         * so a cart can show how much of a line is on backorder BEFORE placement,
+         * when `backorderedQuantity` is still 0 — through
+         * `pricing.backorderedQuantityForCart(variant, quantity)`, which yields no
+         * hint at all when this is `null` (never read `null` as 0).
+         */
+        saleable: number | null;
         product: {
             id: string;
             name: string;
@@ -579,22 +893,42 @@ export interface FulfillmentLine {
     orderLineId: string;
     quantity: number;
 }
+/**
+ * A shipment created for (part of) an order. `trackingCode` is the carrier
+ * barcode — feed it to `commerce.trackShipment(trackingCode, postalCode)`
+ * for live tracking history.
+ */
 export interface Fulfillment {
     id: string;
+    /** Fulfillment FSM state, e.g. Pending, Shipped, Delivered, Cancelled. */
     state: string;
+    /** Human-readable fulfillment/shipping method description. */
     method: string;
     trackingCode: string | null;
     createdAt: string;
     updatedAt: string;
     lines: FulfillmentLine[];
 }
+/**
+ * A payment recorded against an order. `method` is the payment-method *code*
+ * (e.g. `manual-payment`, `mollie-payment`) — drives storefront invoice-vs-PSP
+ * routing. `transactionId` is the PSP receipt; null for manual/offline methods.
+ */
 export interface OrderPayment {
     id: string;
+    /** Payment-method code, e.g. `mollie-payment` or `manual-payment`. */
     method: string;
+    /** Amount captured by this payment, in minor units. */
     amount: number;
+    /** Payment FSM state, e.g. Authorized, Settled, Declined, Cancelled. */
     state: string;
+    /** PSP transaction reference; null for manual/offline payments. */
     transactionId: string | null;
 }
+/**
+ * A shipping charge applied to an order. The selected method's name/code feeds
+ * order-detail rendering; `priceWithTax` is the charged amount in minor units.
+ */
 export interface ShippingLine {
     shippingMethod: {
         id: string;
@@ -608,7 +942,9 @@ export interface Order {
     code: string;
     state: string;
     active: boolean;
+    /** When the order (cart) was created — ISO-8601 instant. */
     createdAt: string;
+    /** When the order left the cart state (was placed) — ISO-8601 instant; null while still an active cart. */
     orderPlacedAt: string | null;
     totalQuantity: number;
     subTotal: number;
@@ -619,10 +955,15 @@ export interface Order {
     totalWithTax: number;
     currencyCode: string;
     lines: OrderLine[];
+    /** Order-level discounts (e.g. order-total promotions, free shipping). */
     discounts: Discount[];
+    /** Tax breakdown grouped by tax rate. */
     taxSummary: OrderTaxSummary[];
+    /** Promotions applied to this order. */
     promotions: OrderPromotion[];
+    /** Shipping charges on the order (selected method + charged price). */
     shippingLines: ShippingLine[];
+    /** Payments recorded against the order (method code, state, PSP receipt). */
     payments: OrderPayment[];
     shippingAddress?: OrderAddress;
     billingAddress?: OrderAddress;
@@ -633,30 +974,102 @@ export interface Order {
         emailAddress: string;
     };
     couponCodes: string[];
+    /**
+     * Shipments for this order. Only selected on placed-order reads
+     * (`getOrderByCode`, customer order history) — absent on cart operations.
+     */
     fulfillments?: Fulfillment[] | null;
+    /**
+     * Tracking pushed by an external fulfilment system, oldest delivery first.
+     * Prefer this over `fulfillments[].trackingCode` for display: one fulfilment can
+     * cover several parcels, which a single tracking code cannot express.
+     */
     externalShipments?: ExternalShipment[] | null;
+    /** Immutable source-aware payment condition captured when this order was accepted. */
     paymentTerms?: OrderPaymentTermsSnapshot | null;
+    /** Immutable Exact-aware delivery terms captured when this order was accepted. */
     deliveryTerms?: OrderDeliveryTermsSnapshot | null;
+    /**
+     * Order-level custom fields.
+     *
+     * Only populated on the order returned by
+     * {@link CommerceModule.setPaymentIntent | commerce.setPaymentIntent} —
+     * ordinary cart and order reads do not select it, so that a client release
+     * cannot break every cart operation against an engine that predates a field.
+     * Keep the buyer's chosen intent in your own state; that call's response is
+     * where to read it back.
+     */
     customFields?: OrderCustomFields | null;
 }
+/**
+ * How the buyer said they would settle this order.
+ *
+ * `pay_now` = paid immediately (iDEAL, card, …), which is what a pay-now
+ * discount promotion looks for; `on_account` = pay later on the net terms the
+ * account carries. Written only by
+ * {@link CommerceModule.setPaymentIntent | commerce.setPaymentIntent}, which
+ * re-prices the order in the same call.
+ */
 export type OrderPaymentIntentValue = 'pay_now' | 'on_account';
+/** The Shop API enum accepted by `commerce.setPaymentIntent`. */
 export type OrderPaymentIntent = 'PAY_NOW' | 'PAY_ON_ACCOUNT';
 export interface OrderCustomFields {
+    /**
+     * The buyer's stated payment intent, or `null` when they never stated one.
+     * Read-only: the only write path is `commerce.setPaymentIntent`.
+     */
     paymentIntent?: OrderPaymentIntentValue | null;
 }
+/**
+ * One parcel, pallet or pickup instruction pushed by the external fulfilment
+ * system.
+ *
+ * `reference` is overloaded by design, because the sending systems overload it:
+ * a parcel carrier sends a tracking URL, a pallet carrier sends a URL *or* a
+ * plain reference, and ex-works sends free-text pickup instructions. Branch on
+ * {@link ExternalShipment.isLink} — derived server-side — to decide between an
+ * anchor and a text block. Never put a non-link reference in an `href`.
+ */
 export interface ExternalShipment {
+    /** Carrier name as the sender reports it, e.g. `PostNL`, `Pallet`, `Ex works`. */
     carrier: string;
+    /** A tracking URL, a carrier reference, or pickup instructions. */
     reference: string;
+    /** True when `reference` is an http(s) URL safe to render as a link. */
     isLink: boolean;
+    /** ISO-8601 dispatch timestamp, or null if the sender omitted it. */
     shippedAt: string | null;
+    /** Which delivery of the order this parcel belongs to. */
     deliveryNumber: string;
 }
+/**
+ * Order minimums in effect on the active channel (inline order-constraints
+ * plugin). Display/pre-validation only — checkout enforces server-side.
+ */
 export interface ActiveChannelOrderConstraints {
+    /**
+     * Minimum vs the GROSS order total, minor units. Null when unset. This is the
+     * channel-wide minimum raised by any price-list minimum applying to the
+     * signed-in customer, so it varies per visitor.
+     */
     minOrderAmountGross: number | null;
+    /**
+     * Minimum vs the NET (tax-exclusive) total, minor units, when a price list
+     * applying to this customer states its minimum ex tax. Independent of
+     * `minOrderAmountGross` — both bind, and neither can be derived from the
+     * other without a tax rate. Null when no net-basis minimum applies.
+     */
     minOrderAmountNet: number | null;
+    /** Minimum total item count, from an applicable price list. Null when unset. */
     minOrderQuantity: number | null;
+    /** Default fulfillment profile minimum vs the NET subtotal, minor units. Null when unset. */
     fulfillmentMinOrderNet: number | null;
     currencyCode: string;
+    /**
+     * True when the signed-in customer's group is exempt from the CHANNEL-wide
+     * minimum. A price-list minimum still applies, so `minOrderAmountGross` may
+     * be non-null while this is true.
+     */
     customerIsExempt: boolean;
 }
 export interface ShippingMethod {
@@ -666,7 +1079,9 @@ export interface ShippingMethod {
     price: number;
     priceWithTax: number;
     metadata?: Record<string, unknown>;
+    /** True when this is the signed-in customer's eligible Exact default. */
     isPreferred: boolean;
+    /** False when the current externally governed customer cannot select this mapping. */
     isDeliveryTermsEligible: boolean;
 }
 export interface PaymentMethod {
@@ -688,13 +1103,33 @@ export interface Customer {
         items: OrderSummary[];
         totalItems: number;
     };
+    /**
+     * Customer groups the customer belongs to in the active channel. Drives
+     * B2B-only UI (navigation, VAT-mode default, order gating) — pricing is
+     * already applied server-side, so groups are for presentation only.
+     */
     groups?: CustomerGroup[];
+    /**
+     * Whether this customer is a trade (B2B) account — i.e. belongs to one of the
+     * channel's configured B2B customer groups. The authoritative signal to gate
+     * B2B UI on, so a storefront never hard-codes a group name. Optional because
+     * a Vendure predating the field simply omits it.
+     *
+     * Presentation only: pricing, the tax display mode and access to quotes /
+     * credit / contract pricing are all resolved server-side regardless.
+     */
     isB2B?: boolean;
 }
+/** A customer group, as exposed to the storefront (identity only). */
 export interface CustomerGroup {
     id: string;
     name: string;
 }
+/**
+ * A price list applying to the active customer. Identity only — prices are
+ * applied server-side; storefronts use this to label which lists (contract /
+ * tier) the signed-in customer is on.
+ */
 export interface CustomerPriceList {
     id: string;
     name: string;
@@ -719,6 +1154,7 @@ export interface OrderSummary {
     id: string;
     code: string;
     state: string;
+    /** Net (excl. tax) order total, in minor units. */
     total: number;
     totalWithTax: number;
     currencyCode: string;
@@ -726,6 +1162,12 @@ export interface OrderSummary {
     lines: Array<{
         id: string;
         quantity: number;
+        /**
+         * Units stock did not cover at placement (backorder); 0 otherwise.
+         * Selected by `getCustomerOrders`; `undefined` from `getCurrentCustomer`.
+         */
+        backorderedQuantity?: number;
+        /** Line total incl. tax, in minor units. */
         linePriceWithTax: number;
         productVariant: {
             id: string;
@@ -745,24 +1187,32 @@ export interface OrderSummary {
         };
     }>;
     fulfillments?: Fulfillment[] | null;
+    /** Tracking pushed by an external fulfilment system. See {@link ExternalShipment}. */
     externalShipments?: ExternalShipment[] | null;
+    /** Immutable source-aware payment condition captured when this order was accepted. */
     paymentTerms?: OrderPaymentTermsSnapshot | null;
+    /** Immutable delivery terms captured when this order was accepted. */
     deliveryTerms?: OrderDeliveryTermsSnapshot | null;
 }
+/** An invoice issued for one of the signed-in customer's orders. */
 export interface CustomerInvoice {
     id: string;
     invoiceNumber: string;
+    /** Issue date (ISO-8601 date). */
     invoicedOn: string;
+    /** Minor units. */
     totalWithTax: number;
     currencyCode: string;
     languageCode: string;
     createdAt: string;
 }
+/** Base64-encoded invoice PDF download. */
 export interface CustomerInvoicePdf {
     base64: string;
     filename: string;
     invoiceNumber: string;
 }
+/** A line that could not be re-added during a `reorder()` call. */
 export interface ReorderSkipped {
     variantId: string;
     quantity: number;
@@ -774,6 +1224,20 @@ export interface ReorderResult {
     addedLines: number;
     skipped: ReorderSkipped[];
 }
+/**
+ * Outcome of {@link CommerceModule.login}. A discriminated union so the
+ * storefront can distinguish a genuine bad password from a migrated/imported
+ * account that needs to set a new password.
+ *
+ * - `success`: signed in; `id`/`identifier` are the current user.
+ * - `password_reset_required`: an imported account with no migrated password.
+ *   The platform has already emailed a reset link — prompt the user to check
+ *   their inbox, do NOT report invalid credentials.
+ * - `account_not_verified`: the account exists but has not been verified yet.
+ *
+ * Genuine invalid credentials still throw a `MutationError` and never produce a
+ * result here.
+ */
 export type LoginResult = {
     status: 'success';
     id: string;
@@ -825,13 +1289,30 @@ export interface MolliePaymentMethod {
         size2x: string;
         svg: string;
     };
+    /**
+     * Mollie's availability status for this method on the order (e.g.
+     * `"activated"`, `"pending-boarding"`). `null` when Mollie omits it.
+     */
     status: string | null;
 }
+/**
+ * A storefront-visible Mollie payment method, ordered per the channel's saved
+ * configuration with hidden methods removed. Returned by
+ * `commerce.getOrderedMolliePaymentMethods`. Decoupled from
+ * {@link MolliePaymentMethod}: this is the curated, channel-ordered shape from
+ * the platform's `payment-config` plugin, not the raw community plugin type.
+ */
 export interface OrderedMollieMethod {
     id: string;
+    /** Mollie method id (e.g. `"ideal"`); pass as `molliePaymentMethodCode`. */
     code: string;
     description: string | null;
+    /** Mollie's icon URL (SVG preferred, 2x PNG fallback); null when omitted. */
     imageUrl: string | null;
+    /**
+     * Mollie's availability status for this method (e.g. `"activated"`). `null`
+     * when Mollie omits it.
+     */
     status: string | null;
 }
 export interface CreateMolliePaymentIntentInput {
@@ -840,11 +1321,21 @@ export interface CreateMolliePaymentIntentInput {
     molliePaymentMethodCode?: string;
     locale?: string;
     immediateCapture?: boolean;
+    /**
+     * Create the intent for a specific order rather than the session's active
+     * order — required when topping up an order in `ArrangingAdditionalPayment`,
+     * or when driving checkout for a non-active order.
+     */
     orderId?: string;
 }
 export interface MolliePaymentIntentResult {
     url: string;
 }
+/**
+ * Minimal order shape returned by `syncMolliePaymentStatus`. Use the `state`
+ * to confirm the order settled (e.g. `PaymentSettled`) after a delayed/missing
+ * Mollie webhook. `null` when no order matches the code.
+ */
 export interface MollieOrderStatusResult {
     id: string;
     code: string;
@@ -899,7 +1390,14 @@ export interface SearchInput {
     term: string;
     collectionSlug?: string;
     collectionId?: string;
+    /**
+     * Filter to products belonging to ALL of these collections (AND). Combine with
+     * `collectionSlugs` to intersect categories across collection groups. A slug
+     * that doesn't resolve in the active channel yields an empty result rather than
+     * widening the search.
+     */
     collectionSlugs?: string[];
+    /** Filter to products belonging to ALL of these collection ids (AND). */
     collectionIds?: string[];
     facetValueIds?: string[];
     facetValueFilters?: FacetValueFilterInput[];
@@ -912,6 +1410,11 @@ export interface SearchInput {
 }
 export interface SearchResultItem {
     productId: string;
+    /**
+     * Orderable variant id for this search row — pass THIS (never `productId`) to
+     * `addToCart`. Under `groupByProduct` it is a representative variant; for the
+     * exact variant on multi-variant products, load `getProduct(slug)`.
+     */
     productVariantId: string;
     productName: string;
     slug: string;
@@ -935,6 +1438,7 @@ export interface SearchResultItem {
         };
     } | null;
     collectionIds: string[];
+    /** Aggregate availability across all stock locations (Meilisearch plugin). */
     inStock: boolean;
 }
 export interface SearchFacetValue {
@@ -955,9 +1459,16 @@ export interface SearchResult {
     totalItems: number;
     facetValues: SearchFacetValue[];
 }
+/** `eq` boolean operator mirroring Vendure's `BooleanOperators` input. */
 export interface BooleanOperators {
     eq?: boolean;
 }
+/**
+ * Subset of Vendure's `ProductFilterParameter` the SDK types explicitly.
+ * `enabled` is the field `getProducts` defaults on; the index signature keeps
+ * the parameter open to the other server-side filter fields without the SDK
+ * having to enumerate them all.
+ */
 export interface ProductFilterParameter {
     enabled?: BooleanOperators;
     [field: string]: unknown;
@@ -965,31 +1476,108 @@ export interface ProductFilterParameter {
 export interface ProductListOptions {
     take?: number;
     skip?: number;
+    /**
+     * How much of each product to fetch. Defaults to `'full'` — the existing
+     * selection, unchanged for every current caller.
+     *
+     * `'card'` asks only for what a grid tile renders. It drops the per-VARIANT
+     * stock reads a tile never shows — `availabilityByLocation`, `stockOnHand`,
+     * `stockAllocated`, `incomingStock`, `projectedSaleable`,
+     * `nextExpectedArrival` — and the product `description`, including the
+     * per-language copy inside `translations`. The variant fields are resolved by
+     * per-variant field resolvers server-side (`availabilityByLocation` issues one
+     * stock query PER VARIANT), so the saving is backend work and SQL statements,
+     * not just bytes.
+     *
+     * **The collection tree and the translated slugs are kept**, so card rows can
+     * still feed `seo.canonicalFor`/`alternatesFor`: `collections` keeps
+     * `parent`, `position`, `translations` and `customFields { isRoutable
+     * isCanonical }`, and the product keeps `translations { languageCode name
+     * slug }`. Also kept: `enabled` and `saleable` (storefronts gate orderability
+     * on `saleable == null || saleable > 0`), `sku`, `stockLevel`,
+     * `priceListName`, `retailPrice`/`retailPriceWithTax`, `priceTiers`, variant
+     * `customFields` (purchase constraints) and `facetValues`. These cost bytes,
+     * not queries.
+     *
+     * Ignored on the deprecated `{ collectionSlug }` path, which reroutes to the
+     * search backend and returns its own already-flat row shape regardless.
+     *
+     * Both shapes are typed `ProductSummary`; the omitted members are optional on
+     * that type, so a card row is a valid — just sparser — `ProductSummary`. Read
+     * a dropped field and you get `undefined`, not a stale value.
+     */
+    detail?: 'card' | 'full';
+    /**
+     * @deprecated Use `getProductsInCollection(slug, options)` instead. This
+     * option silently reroutes the call through the search backend, whose rows
+     * are flatter than the products list (single synthesised variant, no `sku`,
+     * `facetValues`, or `collections`) — the named method makes that shape
+     * explicit. The option keeps working for now.
+     */
     collectionSlug?: string;
+    /**
+     * Vendure's `products` query cannot sort by price — `ProductSortParameter`
+     * has no such field (price lives on variants). For price-sorted listings use
+     * `getProductsInCollection` or `searchProducts`, both of which sort by price
+     * server-side.
+     */
     sort?: {
         name?: 'ASC' | 'DESC';
         createdAt?: 'ASC' | 'DESC';
     };
+    /**
+     * Vendure `ProductFilterParameter`. When omitted, `getProducts` defaults to
+     * `{ enabled: { eq: true } }` so disabled products never leak into an
+     * unfiltered listing. An explicit `filter` REPLACES the default — but note
+     * the Shop API additionally forces `enabled: { eq: true }` server-side, so
+     * no filter can surface disabled products.
+     */
     filter?: ProductFilterParameter;
+    /**
+     * @deprecated The Shop API forces `enabled: { eq: true }` server-side, so
+     * `enabled: false` cannot surface disabled products; the shorthand is
+     * meaningless. Disabled products are only reachable through the Admin API.
+     */
     enabled?: boolean;
 }
+/** Options for `getProductsInCollection` — the search-backed collection listing. */
 export interface CollectionProductListOptions {
     take?: number;
     skip?: number;
+    /** The search backend sorts by `name` or `price` (unlike the products list, which cannot sort by price). */
     sort?: {
         name?: 'ASC' | 'DESC';
         price?: 'ASC' | 'DESC';
     };
 }
+/**
+ * A product card row from the search backend, as returned by
+ * `getProductsInCollection`. Honest projection of a search hit: exactly one
+ * synthesised variant, and none of the fields the search index does not carry
+ * (`sku`, `facetValues`, `collections`). Structurally a subset of
+ * `ProductSummary`, so card components consuming `{ featuredAsset,
+ * variants[0] }` work with either. Load `getProduct(slug)` for the full
+ * variant/asset tree.
+ */
 export interface CollectionProductSummary {
     id: string;
     name: string;
     slug: string;
     description: string;
+    /**
+     * Synthesised from the search row's single preview URL — every preset
+     * points at the same image and `source` is empty.
+     */
     featuredAsset: Asset | null;
+    /** Exactly one synthesised variant per row (search groups by product). */
     variants: [CollectionProductVariant];
 }
+/** The single synthesised variant on a `CollectionProductSummary`. */
 export interface CollectionProductVariant {
+    /**
+     * Orderable variant id — pass THIS (never the product id) to `addToCart`.
+     * A representative variant for multi-variant products.
+     */
     id: string;
     name: string;
     price: number;
@@ -1013,15 +1601,35 @@ export interface FavoriteVariant {
     priceWithTax: number;
     currencyCode: string;
     stockLevel: string;
+    /** ATP numbers — `null` when the channel does not expose operational stock. */
     stockOnHand: number | null;
     stockAllocated: number | null;
     saleable: number | null;
+    /**
+     * Incoming-stock numbers — additionally `null` unless the signed-in customer's
+     * group may see incoming stock. `nextExpectedArrival` is the earliest FUTURE
+     * arrival (ISO 8601, never past) and is `null` when every open line is overdue,
+     * even while `incomingStock > 0`.
+     */
     incomingStock: number | null;
     projectedSaleable: number | null;
     nextExpectedArrival: string | null;
+    /**
+     * Units BEYOND `saleable` the signed-in customer may order on backorder right
+     * now. The quantity ceiling is `max(0, saleable) + backorderAllowance` (see
+     * `maxOrderableQuantity` in `@sixtyninecommerce/client/pricing`). `null` when
+     * the question does not apply — anonymous, group may not backorder, or the
+     * channel hides stock — treat exactly like today; `0` = denied; a large
+     * value (2,000,000,000) is the "unlimited" sentinel. A snapshot: the server
+     * re-checks on add-to-cart and at placement and refuses with the usual
+     * `InsufficientStockError` / `INSUFFICIENT_STOCK`, whose `quantityAvailable`
+     * then already includes the allowance.
+     */
+    backorderAllowance: number | null;
     priceListName: string | null;
     retailPrice: number | null;
     retailPriceWithTax: number | null;
+    /** Tax rate applied to this price in the active channel/zone, e.g. `{ value: 21 }` for 21% VAT. */
     taxRateApplied: {
         value: number;
     } | null;
@@ -1080,6 +1688,7 @@ export interface PaginatedList<T> {
 export interface ResolvedContent {
     data?: Record<string, unknown>;
     item?: Record<string, unknown>;
+    /** Resolved field values keyed by field slug (locale-filtered). */
     values?: Record<string, unknown>;
     collection?: {
         id: string;
@@ -1095,6 +1704,10 @@ export interface ResolvedContent {
         path: string;
     }>;
     slug_translations?: Record<string, string>;
+    /**
+     * Derived SEO metadata block (from the standard SEO field group). `null` when
+     * the item/page carries no SEO fields. Feed to `parseCmsItemMetadata`.
+     */
     metadata?: Record<string, unknown> | null;
 }
 export interface SitemapEntry {
@@ -1103,7 +1716,9 @@ export interface SitemapEntry {
     title: string | null;
     collection_slug: string | null;
     updated_at: string;
+    /** Present only for collection landing pages (basePath routes). */
     type?: 'collection_page';
+    /** Present only when the request specified a language_code. */
     language_code?: string;
 }
 export interface ContentItemSummary {
@@ -1115,6 +1730,11 @@ export interface ContentItemSummary {
     collection_title_field_slug: string | null;
     title: string | null;
 }
+/**
+ * Channel-wide CMS search query. All fields optional — supplying only `q`
+ * searches across every collection in the store. Use `collectionId` or
+ * `collectionSlug` to scope results.
+ */
 export interface ContentSearchQuery {
     q?: string;
     collectionId?: string;
@@ -1122,9 +1742,15 @@ export interface ContentSearchQuery {
     parentId?: string;
     limit?: number;
     offset?: number;
+    /** Meilisearch sort spec, e.g. `'updated_at:desc'`. */
     sort?: string;
     languageCode?: string;
 }
+/**
+ * A single CMS content item search hit. Field values are flattened on the
+ * document with locale-suffixed keys (`title_en`, `title_nl`, ...) — index
+ * with `[fieldSlug]` or `[fieldSlug + '_' + languageCode]` as needed.
+ */
 export interface ContentSearchHit {
     id: string;
     channel_id: string;
@@ -1166,6 +1792,7 @@ export interface CollectionPageValues {
     fields: CollectionFieldDefinition[];
     values: Record<string, unknown>;
 }
+/** A CMS collection (content type) as returned by `GET /collections`. */
 export interface CmsCollection {
     id: string;
     name: string;
@@ -1181,6 +1808,11 @@ export interface CmsCollection {
 export interface CmsCollectionDetail extends CmsCollection {
     fields: CollectionFieldDefinition[];
 }
+/**
+ * A collection item from the direct CMS item endpoints. `values` holds the
+ * item's field values keyed by field slug, locale-merged when a
+ * `languageCode` was requested. Public callers only ever see published items.
+ */
 export interface CmsCollectionItem {
     id: string;
     collectionId: string;
@@ -1191,7 +1823,9 @@ export interface CmsCollectionItem {
     createdAt: string;
     updatedAt: string;
     values: Record<string, unknown>;
+    /** Per-language slug overrides. Present on single-item reads. */
     slug_translations?: Record<string, string>;
+    /** Forward-compat: additional entity fields the CMS may add. */
     [key: string]: unknown;
 }
 export interface CmsCollectionItemList {
@@ -1199,8 +1833,10 @@ export interface CmsCollectionItemList {
     total: number;
 }
 export interface CollectionItemsQuery {
+    /** Filter by parent item; pass `'root'` for top-level items. */
     parentId?: string;
     slug?: string;
+    /** Full-text search within the collection (Meilisearch-assisted). */
     search?: string;
     sort?: string;
     languageCode?: string;
@@ -1221,10 +1857,19 @@ export interface FormField {
     label: string;
     type: string;
     required: boolean;
+    /** Presentational config (e.g. select option labels). */
     config: Record<string, unknown>;
+    /**
+     * Effective per-field validation constraints the server enforces on submit
+     * (min/max length, numeric range, options, pattern), resolved from the
+     * field's `validation` first and `config` as a fallback. Contains only
+     * recognized constraint keys. Mirror it to validate client-side. See
+     * {@link FormFieldTypeDescriptor} / `content.getFormFieldTypes()`.
+     */
     validation: Record<string, unknown>;
     position: number;
 }
+/** A form-level translation as emitted by the public projection. */
 export interface FormTranslation {
     languageCode: string;
     title: string;
@@ -1236,8 +1881,11 @@ export interface FormDefinition {
     id: string;
     name: string;
     slug: string;
+    /** Where the storefront should send the visitor after a successful submit. */
     redirectUrlOnSuccess: string | null;
+    /** True when the form has internal-notification recipients configured (addresses are never exposed). */
     hasNotifications: boolean;
+    /** True when a visitor confirmation email will be sent on submit. */
     sendsConfirmation: boolean;
     fields: FormField[];
     translations: FormTranslation[];
@@ -1245,6 +1893,12 @@ export interface FormDefinition {
     submitMethod: string;
     submitHeaders: Record<string, string>;
 }
+/**
+ * A form as returned by `content.listForms()`. Mirrors the public projection.
+ * NOTE: list responses populate id/name/slug/redirect + the email booleans;
+ * `fields` and `translations` arrive EMPTY in list context — fetch a single
+ * form via `getForm`/`getFormBySlug` to load them.
+ */
 export interface FormSummary {
     id: string;
     name: string;
@@ -1258,8 +1912,11 @@ export interface FormSummary {
 export interface FormListOptions {
     limit?: number;
     offset?: number;
+    /** Case-insensitive match against the form name. */
     search?: string;
+    /** Sort field; prefix with `-` for descending (name, created_at, updated_at). */
     sort?: string;
+    /** Locale for the projected field labels. Defaults to the client language. */
     locale?: string;
 }
 export interface FormListResult {
@@ -1268,40 +1925,66 @@ export interface FormListResult {
         total: number;
     };
 }
+/** One constraint key a field type honors (see {@link FormFieldTypeDescriptor}). */
 export interface FormFieldTypeConstraint {
     key: string;
     valueType: 'integer' | 'number' | 'string' | 'string[]';
     description: string;
 }
+/**
+ * Describes a form field type and the config/validation constraints it honors.
+ * The SDK ships a static mirror as {@link FORM_FIELD_TYPES}; the same data is
+ * served live by `content.getFormFieldTypes()` (GET /forms/field-types).
+ */
 export interface FormFieldTypeDescriptor {
     type: string;
     label: string;
     description: string;
+    /** Shape of the value a submission sends for this field. */
     valueType: string;
+    /** Constraint keys honored on submit; resolved from `validation` first, then `config`. */
     constraints: FormFieldTypeConstraint[];
     notes?: string;
 }
+/** The slug shape one authoring surface enforces (form slug or field slug). */
 export interface FormSlugRule {
+    /** Source of the regex the CMS validates against. */
     pattern: string;
     maxLength: number;
     description: string;
     validExamples: string[];
     invalidExamples: string[];
 }
+/**
+ * Slug rules for form authoring: form slugs are HYPHEN-separated, field slugs
+ * are UNDERSCORE-separated. Shipped statically as {@link FORM_SLUG_RULES} and
+ * served live in the field-types registry response.
+ */
 export interface FormSlugRules {
     form: FormSlugRule;
     field: FormSlugRule;
 }
+/** Everything GET /forms/field-types carries: the field types plus the slug rules. */
 export interface FormFieldTypeRegistry {
     fieldTypes: FormFieldTypeDescriptor[];
     slugRules: FormSlugRules;
 }
+/**
+ * Result of `submitForm` — discriminate on `success`. Field-validation
+ * failures RESOLVE with `success: false` + per-field errors (render them
+ * inline next to the fields); rate limits (429, carries
+ * `retryAfterSeconds`), transport failures, and server errors still throw
+ * `StorefrontError`.
+ */
 export type FormSubmissionResult = {
     success: true;
+    /** Stored submission id. */
     id: string;
+    /** ISO-8601 creation timestamp. */
     createdAt: string;
 } | {
     success: false;
+    /** Per-field validation errors, in the CMS's field order. */
     errors: Array<{
         field: string;
         code?: string;
@@ -1342,8 +2025,21 @@ export interface RouteEntry {
     slug?: string;
     updated_at?: string;
     source?: string;
+    /**
+     * Only set on `product` routes. A product listed under multiple collections
+     * emits one route per collection; exactly one — the canonical URL home — is
+     * `true`, the rest `false`. Filter to `canonical !== false` to get the
+     * deduplicated (one-per-product) URL set. `undefined` on `cms`/`collection`
+     * routes, which are already one-per-entity.
+     */
     canonical?: boolean;
 }
+/**
+ * A manifest entry as `findRoute` returns it, plus the cache tags the page's
+ * reads should carry — `product:<id>` / `collection:<id>`, none for CMS pages.
+ * Load the page by `id` (`getProductById`, `getCollectionById`,
+ * `getProductsInCollectionById`) and those tags are already on its reads.
+ */
 export interface ResolvedRoute extends RouteEntry {
     readonly cacheTags: readonly string[];
 }
@@ -1371,6 +2067,7 @@ export interface ConvertedAmount {
     rate: string;
     rateDate: string;
 }
+/** One entry of a `convertToMultiple()` result. */
 export interface BulkConversionResult {
     currency: string;
     amount: string;
@@ -1383,6 +2080,7 @@ export interface PriceDisplay {
     retailPrice: number | null;
     retailPriceWithTax: number | null;
     priceListName: string | null;
+    /** Tax rate percentage applied to this price (e.g. `21`), or null if unknown. */
     taxRate: number | null;
     hasDiscount: boolean;
     discountPercentage: number | null;
@@ -1392,33 +2090,68 @@ export interface TierTableEntry {
     minQuantity: number;
     price: number;
     priceWithTax: number;
+    /** Tax rate percentage applied to this tier's price (e.g. `21`), or null if unknown. */
     taxRate: number | null;
     discountLabel: string | null;
     savingsPercentage: number | null;
 }
+/**
+ * Which tax figure to display. `gross` = tax-inclusive (BTW "incl."),
+ * `net` = tax-exclusive (BTW "excl."). The platform always returns both the
+ * net (`price`) and gross (`priceWithTax`) figures, so switching modes never
+ * recomputes tax — it just picks the server-authoritative field.
+ */
 export type TaxDisplayMode = 'gross' | 'net';
+/**
+ * Channel-wide display default (`Channel.customFields.taxDisplayDefault`).
+ * `channel` means "follow `pricesIncludeTax`", which is what every storefront
+ * did before the policy existed.
+ */
 export type TaxDisplayDefault = 'channel' | 'gross' | 'net';
+/**
+ * B2B override (`Channel.customFields.taxDisplayB2b`). `inherit` leaves trade
+ * accounts on the channel default.
+ */
 export type TaxDisplayB2bMode = 'inherit' | 'gross' | 'net';
+/**
+ * The channel's price-display policy, as parsed from `activeChannel.customFields`
+ * by `parseTaxDisplayPolicy`. Feed it to `resolveTaxDisplayMode` to preview a
+ * mode offline; the authority is `getTaxDisplayMode()`.
+ */
 export interface TaxDisplayPolicy {
     default: TaxDisplayDefault;
     b2b: TaxDisplayB2bMode;
+    /** Upper-case ISO-3166 alpha-2 codes. Empty = the country rule is off. */
     countries: readonly string[];
 }
+/** The per-shopper facts `resolveTaxDisplayMode` judges. */
 export interface TaxDisplayInputs {
+    /** Member of one of the channel's configured B2B customer groups (`Customer.isB2B`). */
     isB2B: boolean;
+    /** The request carries `x-order-scope: trade` — the dealer storefront. */
     isTrade: boolean;
+    /** The shopper's country: active order shipping address, else their default one. */
     countryCode: string | null;
+    /** `Channel.pricesIncludeTax` — the STORAGE mode, not a display decision. */
     pricesIncludeTax: boolean;
 }
+/**
+ * A resolved mode cached against the identity it was resolved for. Stored on
+ * {@link StoreContext.taxDisplay}; `stamp` is `identityStamp(ctx)`.
+ */
 export interface ResolvedTaxDisplay {
     stamp: string;
     mode: TaxDisplayMode;
 }
 export interface DisplayPrice {
+    /** The amount to show, in minor units, for the requested mode. */
     amount: number;
+    /** The strikethrough/retail amount for the requested mode, or null. */
     retailAmount: number | null;
     currencyCode: string;
+    /** True when `amount` includes tax (i.e. mode was `gross`). */
     isGross: boolean;
+    /** True when a higher retail amount exists for the same mode. */
     hasDiscount: boolean;
 }
 export interface VariantPriceData {
@@ -1469,6 +2202,11 @@ export interface PropertyConfig {
     maxLength?: number;
     allowedCollectionIds?: string[];
     filterableFieldSlugs?: string[];
+    /**
+     * For `product` field type: strict filter applied in the admin UI to
+     * narrow the picker. Storefront callers can ignore this — the selected
+     * product IDs are already stored in `PropertyValue.value` (as `string[]`).
+     */
     productFilter?: {
         filters?: Array<{
             property_slug: string;
@@ -1505,6 +2243,18 @@ export interface ProductPropertyGroupValues {
     group: PropertyGroup;
     values: PropertyValue[];
 }
+/**
+ * A product's property values flattened to a `slug → value` record (the shape
+ * a product-detail view actually renders). Produced by
+ * `commerce.mapProductProperties(...)`.
+ *
+ * Values keep their stored JSON type: `string` (string/text/enum fields),
+ * `boolean`, `number`, or `string[]` (multi_enum / product-reference fields).
+ *
+ * CAVEAT — `content_item` fields (e.g. `producer_winehouse`) store a **CMS
+ * content-item id string**, NOT a human-readable name. To display the producer,
+ * resolve that id against the CMS content API; do not render it verbatim.
+ */
 export type ProductPropertyRecord = Record<string, unknown>;
 export type PresetName = 'xxs' | 'xs' | 's' | 'm' | 'l' | 'xl';
 export interface ResponsiveImageData {
@@ -1613,8 +2363,129 @@ export interface ReviewMediaUploadResult {
     preview: string;
     mimeType: string;
 }
-export type CustomerSubscriptionStatus = 'TRIAL' | 'ACTIVE' | 'PAUSED' | 'PAST_DUE' | 'CANCELLED' | 'EXPIRED' | 'COMPLETED';
+export type CustomerSubscriptionStatus = 'incomplete' | 'trial' | 'active' | 'paused' | 'past_due' | 'cancelled' | 'expired' | 'completed' | 'INCOMPLETE' | 'TRIAL' | 'ACTIVE' | 'PAUSED' | 'PAST_DUE' | 'CANCELLED' | 'EXPIRED' | 'COMPLETED';
+export type SubscriptionFirstChargeTiming = 'immediate' | 'after_interval';
+export type SubscriptionLifecycleAction = 'pause' | 'resume' | 'skip' | 'reschedule' | 'cancel' | 'undoCancellation';
+export interface SubscriptionProduct {
+    variantId: string;
+    quantity: number;
+    name: string;
+    sku: string;
+}
+export interface SubscriptionAllowedAction {
+    action: string;
+    allowed: boolean;
+    reason: string | null;
+}
+export interface SubscriptionUpcomingPayment {
+    dueAt: string | null;
+    amount: number;
+    currencyCode: string;
+    /**
+     * The outstanding cycle's payment state (`ready`, `processing`, `pending`,
+     * `action_required`, `unknown`, `failed`, or `charged_back` — a paid cycle the
+     * bank reversed), else a live checkout's state, else `scheduled`, `paused` or
+     * `none`. `failed` and `charged_back` are recovered with
+     * `recoverMySubscriptionPayment`.
+     */
+    state: string;
+    nextRetryAt: string | null;
+    checkoutUrl: string | null;
+}
+export interface SubscriptionPurchasePreview {
+    planId: string;
+    planName: string;
+    /**
+     * What the customer is charged per cycle, in minor units: products, shipping and
+     * the tax of their zone included. Pass it back as `expectedAmount` when starting.
+     */
+    amount: number;
+    /**
+     * Whether plan prices on this channel include tax. When false the plan price is
+     * net and `amount` adds the customer's VAT (none under reverse charge).
+     */
+    pricesIncludeTax: boolean;
+    /** `amount` without tax. */
+    netAmount: number;
+    /** The tax in `amount` for the customer's tax zone. */
+    taxAmount: number;
+    currencyCode: string;
+    firstPaymentAt: string;
+    firstChargeTiming: SubscriptionFirstChargeTiming;
+    billingInterval: string;
+    billingIntervalCount: number;
+    trialDays: number;
+    trialEndsAt: string | null;
+    minCycles: number | null;
+    maxCycles: number | null;
+    customerChangeCutoffHours: number;
+    cutoffAt: string | null;
+    mandateVerificationAmount: number;
+    products: SubscriptionProduct[];
+}
+export interface SubscriptionPurchaseInput {
+    planId: string;
+    provider?: 'mollie' | 'stripe';
+    mandateId?: string;
+    returnUrl: string;
+    /** Persist this key for the purchase; reuse it when retrying the same request. */
+    requestKey: string;
+    /**
+     * The previewed `amount`. When given, the purchase is rejected — before any
+     * payment starts — if the price changed since the preview; preview again.
+     */
+    expectedAmount?: number;
+}
+export interface SubscriptionPaymentActionInput {
+    requestKey: string;
+    returnUrl: string;
+    provider?: 'mollie' | 'stripe';
+}
+export interface SubscriptionLifecycleCommand {
+    action: SubscriptionLifecycleAction;
+    requestKey: string;
+    date?: string;
+    reason?: string;
+}
+export interface SubscriptionChangePreview {
+    allowed: boolean;
+    reason: string | null;
+    nextRenewalAt: string | null;
+    cancellationEffectiveAt: string | null;
+    committedPayment: boolean;
+    remainingPaidCycles: number;
+}
+export interface SubscriptionPurchaseResult {
+    id: string;
+    subscriptionId: string;
+    state: string;
+    checkoutUrl: string | null;
+    expiresAt: string | null;
+    currentStatus: string | null;
+    paymentActionRequired: boolean;
+    nextRenewalAt: string | null;
+}
 export interface CustomerSubscription {
+    billingIntervalCount: number;
+    trialEndsAt: string | null;
+    minCycles: number | null;
+    maxCycles: number | null;
+    paidCycleCount: number;
+    firstChargeTiming: SubscriptionFirstChargeTiming;
+    customerChangeCutoffHours: number;
+    cutoffAt: string | null;
+    cancellationRequested: boolean;
+    cancellationEffectiveAt: string | null;
+    earliestCancellationAt: string | null;
+    remainingPaidCycles: number;
+    committedPayment: boolean;
+    resumeAt: string | null;
+    retainedResumeAt: string | null;
+    earliestResumeAt: string;
+    allowedActions: SubscriptionAllowedAction[];
+    products: SubscriptionProduct[];
+    paymentActionRequired: boolean;
+    upcomingPayment: SubscriptionUpcomingPayment;
     id: string;
     planName: string;
     currencyCode: string;
@@ -1627,11 +2498,19 @@ export interface CustomerSubscription {
     cancelAtPeriodEnd: boolean;
     createdAt: string;
 }
+/** Customer-safe subscription plan for the storefront catalogue. */
 export interface SubscriptionPlanPublic {
+    firstChargeTiming: SubscriptionFirstChargeTiming;
+    customerChangeCutoffHours: number;
     id: string;
     name: string;
     description: string | null;
     currencyCode: string;
+    /**
+     * Price per cycle in minor units, shipping included, on the channel's price
+     * basis: gross when the channel's prices include tax, otherwise net. Use
+     * `previewSubscriptionPurchase` for the amount a customer is charged.
+     */
     price: number;
     billingInterval: string;
     billingIntervalCount: number;
@@ -1639,17 +2518,21 @@ export interface SubscriptionPlanPublic {
     minCycles: number | null;
     maxCycles: number | null;
 }
+/** Customer-safe view of a stored payment mandate. */
 export interface MyPaymentMandate {
     id: string;
     provider: string;
     mandateMethod: string | null;
+    /** 'pending' | 'valid' | 'invalid' | 'revoked' */
     mandateStatus: string;
     isDefault: boolean;
     createdAt: string;
 }
 export interface SetupPaymentMandateResult {
     mandate: MyPaymentMandate;
+    /** Mollie checkout URL to redirect the customer to (null for Stripe). */
     checkoutUrl: string | null;
+    /** Stripe SetupIntent client secret (null for Mollie). */
     clientSecret: string | null;
 }
 export type QuoteStatus = 'draft' | 'requested' | 'in_review' | 'approved' | 'declined' | 'expired' | 'converted_to_order' | 'cancelled';
@@ -1657,16 +2540,62 @@ export interface QuoteLine {
     id: string;
     productVariantId: string;
     quantity: number;
+    /** Minor units in the quote currency. Null until a sales rep prices the line. */
     unitPrice: number | null;
+    /**
+     * Line-level discount the rep applied. `percentage` is basis points
+     * (10000 = 100%); `fixed` is whole-line minor units. Null when no discount.
+     */
     discountType: 'percentage' | 'fixed' | null;
+    /** Discount magnitude (basis points for `percentage`, minor units for `fixed`). */
     discountValue: number;
     discountLabel: string | null;
     position: number;
+    /**
+     * Variant display name at read time, in the request's language. `null` when
+     * the variant has been deleted or left the channel — render a placeholder
+     * rather than scanning the catalogue for it.
+     *
+     * Optional, like the five fields below: they are `undefined` against a
+     * Vendure that predates them, which the client detects once and then stops
+     * asking for (see `createQuotesMethods`).
+     */
     productName?: string | null;
+    /** Variant SKU at read time. `null` under the same conditions as `productName`. */
     sku?: string | null;
+    /**
+     * Effective tax rate for this line as a PERCENT — 21 for 21%, and fractional
+     * where the statutory rate is (13.5 in IE, 8.1 in CH). It is the variant's
+     * own applied TaxRate, the rate the converted order is charged at; never
+     * assume a national rate. `null` when the variant is unavailable.
+     */
     taxRate?: number | null;
+    /**
+     * Per-unit GROSS (incl. tax) price in minor units, with the whole-line
+     * discount already amortised across the units. `null` when the variant is
+     * unavailable, and while the line is still unpriced (`unitPrice` is `null`,
+     * i.e. a draft or requested quote) — render a placeholder, never `0`.
+     *
+     * Derived from `lineTotalWithTax / quantity`, so it is the quote's own
+     * agreed per-unit figure: `unitPriceWithTax × quantity` reconciles with the
+     * line total exactly, and may differ from the variant's catalogue gross
+     * unit price by a rounding unit.
+     */
     unitPriceWithTax?: number | null;
+    /**
+     * NET (excl. tax) line total in minor units, after discount. `null` when the
+     * variant is unavailable or the line is still unpriced.
+     */
     lineTotal?: number | null;
+    /**
+     * GROSS (incl. tax) line total in minor units, after discount — what this
+     * line adds to the payable total. `null` when the variant is unavailable or
+     * the line is still unpriced.
+     *
+     * This is the quote's OWN line maths. The order `acceptQuote` creates
+     * re-prices per unit, so an order total can differ from the sum of these by
+     * a minor unit per line when the discount does not divide evenly.
+     */
     lineTotalWithTax?: number | null;
     createdAt: string;
     updatedAt: string;
@@ -1681,6 +2610,7 @@ export interface Quote {
     expiresAt: string | null;
     salesRepUserId: string | null;
     customerNotes: string | null;
+    /** Set once the quote has been accepted and converted to an Order. */
     convertedOrderId: string | null;
     lines: QuoteLine[];
     createdAt: string;
@@ -1702,6 +2632,11 @@ export interface CreateQuoteRequestInput {
     }>;
     customerNotes?: string;
 }
+/**
+ * Lifecycle state of a return, derived from its status log. Customers can
+ * only cancel while still `requested`; everything after that is merchant- or
+ * system-driven.
+ */
 export type CustomerReturnState = 'requested' | 'approved' | 'rejected' | 'cancelled' | 'items_received' | 'settlement_pending' | 'settlement_failed' | 'settled';
 export type CustomerReturnSettlementMethod = 'refund' | 'store_credit';
 export type CustomerReturnReasonCode = 'damaged' | 'defective' | 'wrong_item' | 'not_as_described' | 'arrived_late' | 'no_longer_needed' | 'order_error' | 'other';
@@ -1712,26 +2647,40 @@ export interface CustomerReturnLine {
     productVariantName: string;
     productVariantSku: string;
     requestedQty: number;
+    /** Null until the merchant approves; 0 means the line was declined. */
     approvedQty: number | null;
+    /** Cumulative units received back by the merchant across all receipts. */
     receivedQty: number;
     restockQty: number;
     writeOffQty: number;
     reasonCode: CustomerReturnReasonCode;
     reasonNote: string | null;
+    /** Snapshot of the order line's prorated unit price incl. tax (minor units). */
     unitPriceWithTax: number;
+    /**
+     * The same snapshot before per-unit rounding; null for returns requested
+     * before the field existed. Multiply by a quantity and round ONCE to get
+     * that quantity's share, exactly as the order line totals itself.
+     */
     unitPriceWithTaxUnrounded: number | null;
+    /** Refund amount for this line (minor units); null until approved. */
     refundAmount: number | null;
 }
+/** A customer-facing return (RMA). All money fields are Int minor units. */
 export interface CustomerReturn {
     id: string;
+    /** Human-facing RMA code, e.g. RMA-000042. */
     code: string;
     state: CustomerReturnState;
     orderId: string;
     orderCode: string;
     currencyCode: string;
     preferredSettlementMethod: CustomerReturnSettlementMethod | null;
+    /** Settlement method actually used; null until settled. */
     settlementMethod: CustomerReturnSettlementMethod | null;
+    /** Shipping refunded on top of line refunds (minor units). */
     shippingRefundAmount: number;
+    /** Total actually settled (minor units); null until settled. */
     settledAmount: number | null;
     customerNote: string | null;
     requestedAt: string;
@@ -1759,39 +2708,74 @@ export interface RequestReturnInput {
     customerNote?: string;
     preferredSettlementMethod?: CustomerReturnSettlementMethod;
 }
+/** Per-order-line returnable quantities for the return-request flow. */
 export interface ReturnableOrderLine {
     orderLineId: string;
     productVariantId: string;
     productVariantName: string;
     productVariantSku: string;
+    /** Units shipped or delivered for this order line. */
     fulfilledQty: number;
+    /** fulfilledQty minus quantities tied up in active returns. */
     returnableQty: number;
+    /** The order line's prorated unit price incl. tax (minor units). */
     unitPriceWithTax: number;
+    /**
+     * The same price before per-unit rounding. Multiply by a quantity and round
+     * ONCE to preview that quantity's refund, exactly as the order line totals
+     * itself.
+     */
     unitPriceWithTaxUnrounded: number;
 }
 export interface CustomerReturnEligibility {
     orderId: string;
     eligible: boolean;
+    /** Why the order is not eligible; null when eligible. */
     reason: string | null;
     returnWindowEndsAt: string | null;
+    /** Only lines with fulfilled quantity appear here. */
     lines: ReturnableOrderLine[];
 }
+/**
+ * The authenticated customer's B2B accounts-receivable credit status in the
+ * current channel. All money fields are in minor units of `currencyCode`.
+ * Returned by `client.credit.getCreditStatus()`; `null` when the customer is
+ * not signed in, has no credit account, or the channel has B2B credit disabled.
+ */
 export interface B2bCreditStatus {
     customerId: string;
     currencyCode: string;
+    /** Outstanding invoiced-but-unpaid ledger balance. */
     balance: number;
+    /** Total value of placed B2B orders not yet invoiced. */
     uninvoicedOrdersTotal: number;
+    /** Total credit exposure (`balance + uninvoicedOrdersTotal`). */
     exposure: number;
+    /** Configured credit limit; `null` when no limit is set. */
     creditLimit: number | null;
+    /** Remaining headroom (`creditLimit - exposure`); `null` when no limit is set. */
     available: number | null;
     overdueInvoiceCount: number;
     overLimit: boolean;
     hasOverdue: boolean;
+    /**
+     * Where `balance` was sourced from. `LOCAL_LEDGER` = computed from the local
+     * AR subledger; `ERP_LIVE` = read live from the ERP; `ERP_UNLINKED` = the
+     * channel is ERP-driven but this customer isn't linked yet (treat the balance
+     * as unavailable rather than zero, and surface a "not linked" notice).
+     */
     balanceSource: CreditBalanceSource;
 }
+/** Where a {@link B2bCreditStatus.balanceSource} balance was sourced from. */
 export type CreditBalanceSource = 'LOCAL_LEDGER' | 'ERP_LIVE' | 'ERP_UNLINKED';
+/** How reliably the source payment condition could be interpreted. */
 export type PaymentTermsClassification = 'SINGLE_DUE_DATE' | 'COMPLEX' | 'UNRESOLVED' | 'UNASSIGNED' | 'CONFLICT';
+/** Assignment and freshness state for externally managed customer payment terms. */
 export type PaymentTermsStatus = 'ASSIGNED' | 'UNASSIGNED' | 'UNRESOLVED' | 'STALE' | 'CONFLICT';
+/**
+ * Source-aware payment terms for the authenticated customer. Exact-backed terms preserve the
+ * original condition code and complex-rule fields rather than reducing every condition to days.
+ */
 export interface CustomerPaymentTerms {
     customerId: string | null;
     source: string;
@@ -1812,15 +2796,25 @@ export interface CustomerPaymentTerms {
     syncedAt: string | null;
     error: string | null;
 }
+/** Payment terms frozen on an order at acceptance, including later remote confirmation metadata. */
 export interface OrderPaymentTermsSnapshot extends Omit<CustomerPaymentTerms, 'customerId'> {
     resolvedAt: string;
     remoteConditionCode: string | null;
     remoteConfirmedAt: string | null;
+    /** True after the ERP confirms a different condition than the accepted snapshot. */
     remoteMismatch: boolean;
 }
+/** Assignment and freshness state for Exact-managed customer delivery terms. */
 export type DeliveryTermsStatus = 'ASSIGNED' | 'UNASSIGNED' | 'UNRESOLVED' | 'STALE' | 'CONFLICT';
+/** Exact's account-level partial-delivery policy, exposed as operational guidance. */
 export type DeliveryAdvice = 'PARTIAL_ALLOWED' | 'COMPLETE_ORDER' | 'PARTIAL_WITHOUT_BACKORDER' | 'UNKNOWN';
+/** Why the placed order uses its selected shipping method. */
 export type DeliverySelectionSource = 'CUSTOMER_DEFAULT' | 'EXPLICIT_OVERRIDE' | 'IMPORTED' | 'UNKNOWN';
+/**
+ * Exact-aware delivery terms for the authenticated customer in the current channel.
+ * The preferred method is a default, not an eligibility restriction; checkout pricing
+ * still comes from the platform's shipping calculator.
+ */
 export interface CustomerDeliveryTerms {
     customerId: string | null;
     source: string;
@@ -1833,18 +2827,22 @@ export interface CustomerDeliveryTerms {
     preferredShippingMethodCode: string | null;
     preferredShippingMethodName: string | null;
     preferredShippingMethodAvailable: boolean;
+    /** Active platform mappings that may be selected as deliberate overrides. */
     eligibleShippingMethodIds: string[];
     incotermStatus: DeliveryTermsStatus;
     incotermCode: string | null;
     incotermVersion: number | null;
     incotermAddress: string | null;
     incotermDescription: string | null;
+    /** Exact dispatch lead time in days; this is not a promised arrival date. */
     shippingLeadDays: number | null;
     deliveryAdvice: DeliveryAdvice | null;
     stale: boolean;
     syncedAt: string | null;
+    /** Customer-safe warning; raw synchronization errors remain Admin-only. */
     warning: string | null;
 }
+/** Delivery terms frozen on an order at acceptance, plus later Exact readback metadata. */
 export interface OrderDeliveryTermsSnapshot {
     source: string;
     managedExternally: boolean;
@@ -1859,7 +2857,9 @@ export interface OrderDeliveryTermsSnapshot {
     platformShippingMethodCode: string | null;
     platformShippingMethodName: string | null;
     platformShippingMethodDescription: string | null;
+    /** Accepted platform shipping quote in order-currency minor units. */
     platformShippingPrice: number | null;
+    /** Accepted platform shipping quote including tax, in order-currency minor units. */
     platformShippingPriceWithTax: number | null;
     preferredShippingMethodId: string | null;
     incotermStatus: DeliveryTermsStatus;
@@ -1880,6 +2880,7 @@ export interface OrderDeliveryTermsSnapshot {
     remoteIncotermAddress: string | null;
     remoteDeliveryDate: string | null;
     remoteConfirmedAt: string | null;
+    /** True after Exact confirms delivery fields that differ from the accepted snapshot. */
     remoteMismatch: boolean;
 }
 export interface VatValidationResult {
@@ -1912,6 +2913,7 @@ export interface DropOffPoint {
     availableDays: number[] | null;
     cutOffTime: string | null;
     carrierId: number | null;
+    /** Distance from the postal code, in metres. */
     distance: number | null;
 }
 export interface DeliveryOptionsInput {
@@ -1928,10 +2930,12 @@ export interface DeliveryTimeFrame {
     start: string;
     end: string;
     priceComment: string | null;
+    /** Base rate for this window in minor units (cents); null when the carrier omits it. Surcharges finalize after shipment creation. */
     price: {
         amount: number;
         currency: string;
     } | null;
+    /** Carrier delivery type of this window (MyParcel: 1 morning, 2 evening, 3 standard, 4 pickup). */
     deliveryType: number | null;
 }
 export interface DeliveryOption {
@@ -1943,14 +2947,21 @@ export interface PickupLocationAddress {
     number: string;
     postalCode: string;
     city: string;
+    /** ISO 3166-1 alpha-2 country code. */
     countryCode: string;
     region?: string;
 }
 export interface PickupLocationOpeningHours {
+    /** 0 = Sunday ... 6 = Saturday. */
     weekday: number;
+    /** `HH:MM` (24-hour). */
     open: string;
     close: string;
 }
+/**
+ * Carrier-agnostic pickup location. Currently MyParcel-backed; future
+ * providers (Sendcloud, Hendriks) implement the same shape.
+ */
 export interface PickupLocation {
     provider: string;
     carrier: number;
@@ -1958,9 +2969,11 @@ export interface PickupLocation {
     name: string;
     address: PickupLocationAddress;
     openingHours?: PickupLocationOpeningHours[];
+    /** Carrier-specific extras. */
     details?: Record<string, unknown>;
 }
 export interface PickupLocationSearchInput {
+    /** ISO 3166-1 alpha-2 country code. */
     countryCode: string;
     postalCode: string;
     carrierId: number;
@@ -1969,6 +2982,7 @@ export interface PickupLocationSearchInput {
     number?: string;
     latitude?: number;
     longitude?: number;
+    /** Search radius in metres. */
     distance?: number;
 }
 export interface ShipmentTrackingHistoryEntry {
@@ -1990,17 +3004,24 @@ export interface CommerceModule {
     getProductById(id: string, options?: RequestOptions): Promise<Product>;
     getProducts(listOptions?: ProductListOptions, options?: RequestOptions): Promise<PaginatedList<ProductSummary>>;
     getProductsInCollection(collectionSlug: string, listOptions?: CollectionProductListOptions, options?: RequestOptions): Promise<PaginatedList<CollectionProductSummary>>;
+    /**
+     * `getProductsInCollection` by collection id — typically `route.id` from the
+     * routes manifest. Tagged `collection:<id>`, which the slug variant cannot be,
+     * so `collection.membership_changed` purges the listing.
+     */
     getProductsInCollectionById(collectionId: string, listOptions?: CollectionProductListOptions, options?: RequestOptions): Promise<PaginatedList<CollectionProductSummary>>;
     getFacets(options?: RequestOptions): Promise<Facet[]>;
     searchProducts(input: SearchInput, options?: RequestOptions): Promise<SearchResult>;
     getActiveOrder(): Promise<Order | null>;
     addToCart(variantId: string, quantity: number): Promise<Order>;
+    /** Add several variants in one call (e.g. favourite-box bundles). */
     addItemsToCart(items: Array<{
         productVariantId: string;
         quantity: number;
     }>): Promise<Order>;
     updateCartLine(lineId: string, quantity: number): Promise<Order>;
     removeFromCart(lineId: string): Promise<Order>;
+    /** Remove every line from the active order, leaving an empty cart. */
     clearCart(): Promise<Order>;
     applyCouponCode(code: string): Promise<Order>;
     removeCouponCode(code: string): Promise<Order>;
@@ -2008,18 +3029,42 @@ export interface CommerceModule {
     setShippingAddress(input: AddressInput): Promise<Order>;
     setBillingAddress(input: AddressInput): Promise<Order>;
     getEligibleShippingMethods(): Promise<ShippingMethod[]>;
+    /** Exact-aware delivery defaults for the signed-in customer, or null when unavailable. */
     getDeliveryTerms(options?: RequestOptions): Promise<CustomerDeliveryTerms | null>;
     setShippingMethod(ids: string[]): Promise<Order>;
+    /** Apply the signed-in customer's currently eligible Exact default shipping method. */
     applyPreferredShippingMethod(): Promise<Order>;
     getEligiblePaymentMethods(): Promise<PaymentMethod[]>;
+    /** Order minimums on the active channel — display/pre-validation; server enforces. */
     getOrderConstraints(): Promise<ActiveChannelOrderConstraints>;
+    /**
+     * Record how the buyer intends to settle this order and return the
+     * **re-priced** order — a pay-now discount promotion only applies once the
+     * engine knows the intent, and a payment method is not chosen until
+     * {@link CommerceModule.addPayment}, long after the totals the buyer is
+     * looking at were computed. Call it whenever the buyer picks or changes a
+     * payment method, before {@link CommerceModule.transitionToArrangingPayment}.
+     */
     setPaymentIntent(intent: OrderPaymentIntent): Promise<Order>;
     transitionToArrangingPayment(): Promise<Order>;
     addPayment(input: PaymentInput): Promise<Order>;
     createStripePaymentIntent(options?: RequestOptions): Promise<StripePaymentIntentResult>;
     getMolliePaymentMethods(input: MolliePaymentMethodsInput, options?: RequestOptions): Promise<MolliePaymentMethod[]>;
+    /**
+     * Mollie payment methods for the given PaymentMethod, ordered per the
+     * channel's saved configuration and with hidden methods removed. Use this
+     * (rather than `getMolliePaymentMethods`) when the storefront should respect
+     * the merchant's curated order + visibility. Returns `[]` when no Mollie API
+     * key is configured for the channel or Mollie is unreachable.
+     */
     getOrderedMolliePaymentMethods(paymentMethodCode: string, options?: RequestOptions): Promise<OrderedMollieMethod[]>;
     createMolliePaymentIntent(input: CreateMolliePaymentIntentInput, options?: RequestOptions): Promise<MolliePaymentIntentResult>;
+    /**
+     * Force-fetch the Mollie payment status and reconcile the order state.
+     * Use as a fallback when the Mollie webhook is delayed or did not arrive
+     * (e.g. local/staging without a public tunnel). Returns `null` when no
+     * order matches `orderCode`.
+     */
     syncMolliePaymentStatus(orderCode: string, options?: RequestOptions): Promise<MollieOrderStatusResult | null>;
     login(email: string, password: string): Promise<LoginResult>;
     register(input: RegisterInput): Promise<{
@@ -2027,11 +3072,25 @@ export interface CommerceModule {
     }>;
     logout(): Promise<void>;
     getCurrentCustomer(): Promise<Customer | null>;
+    /**
+     * Price lists currently applying to the signed-in customer (identity only,
+     * sorted by resolution priority). Empty for anonymous visitors with no
+     * channel-wide lists.
+     */
     getActiveCustomerPriceLists(options?: RequestOptions): Promise<CustomerPriceList[]>;
     getCustomerOrders(options?: OrderListOptions): Promise<PaginatedList<OrderSummary>>;
+    /**
+     * Add every line of a previous order to the active cart. Returns the new
+     * active order plus a list of lines that could not be added (e.g. variant
+     * removed, out of stock).
+     */
     reorder(orderCode: string): Promise<ReorderResult>;
     getCollections(listOptions?: CollectionListOptions, options?: RequestOptions): Promise<Collection[]>;
     getCollection(slug: string, options?: RequestOptions): Promise<CollectionDetail>;
+    /**
+     * A collection by id — typically `route.id` from the routes manifest. Tagged
+     * `collection:<id>`; throws a `NOT_FOUND` StorefrontError (404) when absent.
+     */
     getCollectionById(id: string, options?: RequestOptions): Promise<CollectionDetail>;
     updateCustomer(input: UpdateCustomerInput): Promise<Customer>;
     updatePassword(currentPassword: string, newPassword: string): Promise<void>;
@@ -2061,11 +3120,18 @@ export interface CommerceModule {
     deleteAddress(id: string): Promise<void>;
     getAvailableCountries(): Promise<Country[]>;
     getOrderByCode(code: string): Promise<Order>;
+    /** Invoices for one of the signed-in customer's own orders. */
     getMyOrderInvoices(orderCode: string): Promise<CustomerInvoice[]>;
+    /** Download one of the signed-in customer's own invoices as a base64 PDF. */
     getMyInvoicePdf(invoiceId: string): Promise<CustomerInvoicePdf>;
     getActiveChannel(): Promise<ActiveChannel>;
     getPropertyGroups(options?: RequestOptions): Promise<PropertyGroup[]>;
     getProductProperties(productId: string, options?: RequestOptions): Promise<ProductPropertyGroupValues[]>;
+    /**
+     * Flatten `getProductProperties(...)` output into a `slug → value` record for
+     * the product-detail view. Pure helper — see `ProductPropertyRecord` for the
+     * `content_item` (producer) caveat.
+     */
     mapProductProperties(groups: ProductPropertyGroupValues[]): ProductPropertyRecord;
     getMySavedLists(): Promise<SavedList[]>;
     getMySavedList(id: string): Promise<SavedList | null>;
@@ -2105,29 +3171,106 @@ export interface CommerceModule {
     voteReview(reviewId: string, isHelpful: boolean): Promise<boolean>;
     reportReview(reviewId: string, reason: string): Promise<boolean>;
     uploadReviewMedia(files: File[]): Promise<ReviewMediaUploadResult[]>;
+    getMySubscription(id: string): Promise<CustomerSubscription | null>;
+    previewSubscriptionPurchase(planId: string, options?: {
+        provider?: 'mollie' | 'stripe';
+        mandateId?: string;
+    }): Promise<SubscriptionPurchasePreview>;
+    startSubscriptionPurchase(input: SubscriptionPurchaseInput): Promise<SubscriptionPurchaseResult>;
+    getSubscriptionPurchaseStatus(id: string): Promise<SubscriptionPurchaseResult>;
+    previewMySubscriptionChange(id: string, input: SubscriptionLifecycleCommand): Promise<SubscriptionChangePreview>;
+    manageMySubscription(id: string, input: SubscriptionLifecycleCommand): Promise<CustomerSubscription>;
+    skipMySubscription(id: string, requestKey: string): Promise<CustomerSubscription>;
+    rescheduleMySubscription(id: string, date: string, requestKey: string): Promise<CustomerSubscription>;
+    undoMySubscriptionCancellation(id: string, requestKey: string): Promise<CustomerSubscription>;
+    replaceMySubscriptionMandate(id: string, input: SubscriptionPaymentActionInput & {
+        provider: 'mollie' | 'stripe';
+    }): Promise<SubscriptionPurchaseResult>;
+    /**
+     * A hosted link that pays the outstanding failed or charged-back cycle again,
+     * without another delivery. Reuse `upcomingPayment.checkoutUrl` while it is live.
+     */
+    recoverMySubscriptionPayment(id: string, input: SubscriptionPaymentActionInput): Promise<SubscriptionPurchaseResult>;
     getMySubscriptions(): Promise<CustomerSubscription[]>;
+    /**
+     * Plans available to subscribe to in the current channel. Public —
+     * works for anonymous visitors. Only enabled plans are returned.
+     */
     getSubscriptionPlans(): Promise<SubscriptionPlanPublic[]>;
+    /**
+     * The active customer's valid or still-pending payment mandates. Poll this
+     * after `setupPaymentMandate` until the mandate flips to `valid`.
+     */
     getMyPaymentMandates(): Promise<MyPaymentMandate[]>;
+    /**
+     * Begin establishing a payment mandate. Returns a `checkoutUrl` (Mollie) or
+     * `clientSecret` (Stripe) for the frontend to complete the setup.
+     */
     setupPaymentMandate(input: {
         provider: string;
         redirectUrl: string;
     }): Promise<SetupPaymentMandateResult>;
-    createSubscription(planId: string, mandateId: string): Promise<CustomerSubscription>;
+    /**
+     * Create a subscription for the active customer against an enabled plan
+     * using one of their valid mandates.
+     */
+    createSubscription(planId: string, mandateId: string, requestKey?: string): Promise<CustomerSubscription>;
+    /** Pause an active or trial subscription owned by the active customer. */
     pauseMySubscription(id: string, reason?: string): Promise<CustomerSubscription>;
+    /** Resume a paused subscription owned by the active customer. */
     resumeMySubscription(id: string): Promise<CustomerSubscription>;
+    /**
+     * Cancel a subscription owned by the active customer. Defaults to
+     * the earliest eligible cancellation date; minimum paid-cycle commitments still apply.
+     */
     cancelMySubscription(id: string, options?: {
         reason?: string;
         immediate?: boolean;
     }): Promise<CustomerSubscription>;
+    /** Returns the active customer's quotes in the current channel. */
     getMyQuotes(options?: QuoteListOptions): Promise<QuoteList>;
+    /** Returns one of the active customer's quotes by id. */
     getMyQuote(id: string): Promise<Quote | null>;
+    /**
+     * Submits a new quote request. Lines are unpriced — a sales rep
+     * prices them later. Requires the customer to belong to a configured
+     * B2B customer group.
+     */
     createQuoteRequest(input: CreateQuoteRequestInput): Promise<Quote>;
+    /**
+     * Accepts a priced+approved quote, producing a real `Order` in
+     * `ArrangingPayment` with the quoted unit prices applied.
+     */
     acceptQuote(id: string): Promise<Order>;
+    /** Cancels a quote owned by the active customer. */
     cancelMyQuote(id: string, reason?: string): Promise<Quote>;
+    /**
+     * Returns the active customer's returns (RMAs) in the current channel,
+     * newest first. Requires an authenticated customer session.
+     */
     getMyReturns(options?: CustomerReturnListOptions): Promise<CustomerReturnList>;
+    /**
+     * Returns one of the active customer's returns by id, or `null` when it
+     * does not exist or belongs to another customer.
+     */
     getMyReturn(id: string): Promise<CustomerReturn | null>;
+    /**
+     * Requests a return (RMA) for fulfilled lines of one of the active
+     * customer's orders. Only allowed when the channel has returns enabled and
+     * the order is inside the return window; quantities are capped at each
+     * line's returnable quantity (see `getReturnableLinesForOrder`).
+     */
     requestReturn(input: RequestReturnInput): Promise<CustomerReturn>;
+    /**
+     * Cancels a return owned by the active customer. Only possible while the
+     * return is still in the `requested` state.
+     */
     cancelMyReturn(id: string): Promise<CustomerReturn>;
+    /**
+     * Per-line returnable quantities and the return window for one of the
+     * active customer's orders — drives the return-request UI. Lines only
+     * appear once they have shipped/delivered quantity.
+     */
     getReturnableLinesForOrder(orderId: string): Promise<CustomerReturnEligibility>;
     getMyVatValidationStatus(): Promise<VatValidationResult | null>;
     setMyVatNumber(vatNumber: string): Promise<VatValidationResult>;
@@ -2135,22 +3278,52 @@ export interface CommerceModule {
     getDropOffPoints(input: DropOffPointInput): Promise<DropOffPoint[]>;
     getDeliveryOptions(input: DeliveryOptionsInput): Promise<DeliveryOption[]>;
     trackShipment(barcode: string, postalCode: string): Promise<ShipmentTrackingInfo | null>;
+    /**
+     * Carrier-agnostic pickup-location search. Currently MyParcel-backed;
+     * future providers (Sendcloud, Hendriks) implement the same shape.
+     */
     findPickupLocations(input: PickupLocationSearchInput): Promise<PickupLocation[]>;
+    /** Persist the customer's chosen pickup location on the active order. */
     selectPickupLocation(location: PickupLocation): Promise<Order>;
+    /** Read the pickup location stored on the active order, or `null`. */
     getActivePickupLocation(): Promise<PickupLocation | null>;
+    /**
+     * Returns the channel's public branding info: identity (logos, name),
+     * theme (primary color), fonts (Google + self-hosted), contact, legal,
+     * social links, and storefront routing config. Asset URLs are resolved
+     * against the channel's CDN domain (or global cdnUrl fallback).
+     *
+     * Used by the `@sixtyninecommerce/create-storefront` CLI for fail-fast scaffolding
+     * validation and at storefront runtime for footer/header/SEO rendering.
+     */
     getBranding(options?: RequestOptions): Promise<BrandingInfo>;
 }
 export interface ContentModule {
     resolvePath(path: string, locale?: string, options?: RequestOptions): Promise<ResolvedContent>;
     getContent(queryOptions: ContentQueryOptions, options?: RequestOptions): Promise<Record<string, unknown>>;
+    /**
+     * Typed channel-wide CMS content search. Pass `collectionId`/`collectionSlug`
+     * to scope, or omit both to search across every collection.
+     */
     searchContent(query: ContentSearchQuery, options?: RequestOptions): Promise<ContentSearchResult>;
     getAsset(id: string, options?: RequestOptions): Promise<CmsAsset>;
     lookupAssets(ids: string[], options?: RequestOptions): Promise<CmsAsset[]>;
     lookupVendureAssetDescriptions(vendureAssetIds: string[], options?: RequestOptions): Promise<Record<string, VendureAssetDescriptionTranslation[]>>;
+    /** Discover the channel's forms (public projection). See {@link FormSummary}. */
     listForms(options?: FormListOptions & RequestOptions): Promise<FormListResult>;
     getForm(id: string, options?: RequestOptions): Promise<FormDefinition>;
     getFormBySlug(slug: string, options?: RequestOptions): Promise<FormDefinition>;
+    /**
+     * The field-type registry (GET /forms/field-types) — every legal field type
+     * and its config/validation schema. Prefer the static {@link FORM_FIELD_TYPES}
+     * constant when a round-trip isn't warranted.
+     */
     getFormFieldTypes(options?: RequestOptions): Promise<FormFieldTypeDescriptor[]>;
+    /**
+     * The same request as {@link ContentModule.getFormFieldTypes}, but keeping the
+     * slug rules the response carries alongside the field types — use it when
+     * authoring forms, so the hyphen/underscore split is known before the write.
+     */
     getFormFieldTypeRegistry(options?: RequestOptions): Promise<FormFieldTypeRegistry>;
     submitForm(id: string, values: Record<string, unknown>, options?: RequestOptions): Promise<FormSubmissionResult>;
     getContentStrings(format?: 'list' | 'export', options?: RequestOptions): Promise<ContentStrings>;
@@ -2171,48 +3344,149 @@ export interface NavigationModule {
     getRoutesByType(type: 'cms' | 'collection' | 'product', languageCode?: string, options?: RequestOptions): Promise<RouteEntry[]>;
 }
 export interface PricingModule {
+    /**
+     * The channel's tax-display STORAGE mode (mirrors
+     * {@link ChannelInfo.pricesIncludeTax}) — which of `price`/`priceWithTax` the
+     * merchant typed in. It is NOT the display decision: use
+     * {@link PricingModule.getTaxDisplayMode} for that. This stays the last-resort
+     * fallback when the mode cannot be resolved.
+     */
     readonly pricesIncludeTax: boolean;
     formatPrice(amount: number, currencyCode?: string, locale?: string): string;
     formatPriceRange(min: number, max: number, currencyCode?: string, locale?: string): string;
     getTierForQuantity(tiers: PriceTier[], quantity: number): PriceTier | null;
     computeTierTable(variant: VariantPriceData): TierTableEntry[];
     getPriceDisplay(variant: VariantPriceData): PriceDisplay;
+    /**
+     * Pick the net-or-gross figure to display for a variant. Never recomputes
+     * tax — selects the server-authoritative `price`/`priceWithTax` (and the
+     * matching retail field) for the requested mode.
+     *
+     * Omit `mode` to use {@link PricingModule.currentTaxDisplayMode}, i.e. the
+     * mode `getTaxDisplayMode()` last resolved for this shopper. Pass one only to
+     * override — a side-by-side incl./excl. table, or a toggle the shopper drove.
+     */
     selectDisplayPrice(variant: VariantPriceData, mode?: TaxDisplayMode): DisplayPrice;
+    /**
+     * The mode this shopper should see prices in, resolved by the server from the
+     * channel's policy (country list → B2B/trade → channel default →
+     * `pricesIncludeTax`). Call it once per request/session and let
+     * `selectDisplayPrice(variant)` default to it.
+     *
+     * Never throws and never blocks a render: an unreachable or older engine
+     * falls back to the channel storage mode (`pricesIncludeTax ? 'gross' :
+     * 'net'`), which is exactly the pre-policy behaviour. Only a real answer is
+     * cached, so a transient failure does not pin the mode for the session.
+     *
+     * The result is cached per identity (auth token + order scope) and is
+     * re-resolved automatically after a sign-in/out, a `setOrderScope`, or a
+     * `setShippingAddress` — moving the order's country can flip the mode. Pass
+     * `{ refresh: true }` to force a round-trip.
+     */
     getTaxDisplayMode(options?: {
         refresh?: boolean;
     }): Promise<TaxDisplayMode>;
+    /**
+     * The last mode {@link PricingModule.getTaxDisplayMode} resolved for the
+     * current identity, without a round-trip — the channel storage mode when
+     * nothing has been resolved yet. Synchronous, for render paths.
+     */
     currentTaxDisplayMode(): TaxDisplayMode;
+    /**
+     * Preview the mode for a hypothetical shopper, offline. Mirrors the engine's
+     * precedence rule for a "who sees what" table or an SSR guess before the
+     * first round-trip — `getTaxDisplayMode()` remains the authority, because
+     * only the server knows the shopper's resolved country.
+     */
     resolveTaxDisplayMode(policy: TaxDisplayPolicy, inputs: TaxDisplayInputs): TaxDisplayMode;
+    /**
+     * Read the channel's display policy off `activeChannel.customFields`.
+     * Lenient — an unreadable value degrades to the pre-policy default.
+     */
     parseTaxDisplayPolicy(fields: unknown): TaxDisplayPolicy;
+    /**
+     * Pre-validate the cart against the channel's order minimums. Pass the object
+     * from `getOrderConstraints()` straight through. The server enforces at the
+     * `ArrangingPayment` transition regardless.
+     */
     validateOrderMinimums(order: {
         totalWithTax: number;
         currencyCode: string;
         totalQuantity?: number;
+        /**
+         * Net (tax-exclusive) total, minor units — required for the
+         * `minOrderAmountNet` check. `subTotal` is preferred over `total` because
+         * the server compares line totals, which exclude shipping. Without one of
+         * them the net check is skipped.
+         */
         subTotal?: number;
         total?: number;
     }, constraints: {
         minOrderAmountGross?: number | null;
         minOrderAmountNet?: number | null;
         minOrderQuantity?: number | null;
+        /** @deprecated Use `minOrderAmountGross`. */
         minOrderAmount?: number | null;
     }): OrderValidationResult;
+    /**
+     * The quantity ceiling for a variant: `max(0, saleable) + backorderAllowance`.
+     * `null` when the channel hides stock — no ceiling to show, let the server
+     * decide, exactly as before backorders. Clamp quantity steppers to it.
+     */
+    maxOrderableQuantity(variant: OrderableStockInput): number | null;
+    /**
+     * Whether a variant is orderable only on backorder: nothing saleable, but an
+     * allowance. The signal to label "Backorder" instead of "Out of stock".
+     */
+    isBackorderOnly(variant: OrderableStockInput): boolean;
+    /**
+     * Units of a cart line stock will not cover — the "N on backorder" hint
+     * before placement, as the server will stamp it. `null` when the channel
+     * hides stock or stock covers the line: show nothing.
+     */
+    backorderedQuantityForCart(variant: Pick<OrderableStockInput, 'saleable'>, quantity: number): number | null;
+}
+/** The two fields the quantity ceiling reads; satisfied by every SDK variant shape. */
+export interface OrderableStockInput {
+    saleable?: number | null;
+    backorderAllowance?: number | null;
 }
 export interface MediaModule {
     assetUrl(path: string): string;
+    /**
+     * Absolute full-resolution URL for an asset's original `source`. Use for the
+     * gallery main/lightbox image — `Asset.source` arrives as a CDN-relative
+     * storage key and must never be rendered directly. Returns `''` for an asset
+     * with an empty `source`.
+     */
     getFullUrl(asset: Asset): string;
     getPresetUrl(asset: Asset, preset: PresetName, format?: 'original' | 'webp'): string;
     getResponsiveImageData(asset: Asset, presets?: PresetName[]): ResponsiveImageData;
 }
 export interface CurrencyModule {
     getExchangeRates(): Promise<ExchangeRate[]>;
+    /** Current rate for a single base→target pair, or `null` when unknown. */
     getExchangeRate(targetCurrency: string): Promise<ExchangeRate | null>;
     convertCurrency(amount: string, fromCurrency: string, toCurrency: string): Promise<ConvertedAmount>;
+    /** Convert from the base currency (EUR) to a target currency. */
     convertFromBase(amount: string, targetCurrency: string): Promise<ConvertedAmount>;
+    /** Convert from a source currency to the base currency (EUR). */
     convertToBase(amount: string, sourceCurrency: string): Promise<ConvertedAmount>;
+    /** Convert one amount into several currencies in a single roundtrip. */
     convertToMultiple(amount: string, fromCurrency: string, toCurrencies: string[]): Promise<BulkConversionResult[]>;
 }
 export interface CreditModule {
+    /**
+     * Returns the signed-in customer's B2B credit status in the current
+     * channel, or `null` when not signed in, no credit account exists, or the
+     * channel has B2B credit disabled. Soft-enforcement only — display the
+     * `overLimit` / `hasOverdue` flags as warnings; the SDK never blocks checkout.
+     */
     getCreditStatus(options?: RequestOptions): Promise<B2bCreditStatus | null>;
+    /**
+     * Returns the signed-in customer's source-aware payment terms (including local B2B terms), or
+     * `null` when the customer is not signed in or has no payment-terms account in this channel.
+     */
     getPaymentTerms(options?: RequestOptions): Promise<CustomerPaymentTerms | null>;
 }
 export interface StorefrontClient {
@@ -2225,13 +3499,20 @@ export interface StorefrontClient {
     readonly currency: CurrencyModule;
     readonly credit: CreditModule;
     readonly seo: import('./seo/types.js').SeoModule;
+    /** Platform-managed URL redirects for this channel. */
     readonly redirects: import('./redirects/types.js').RedirectStore;
     readonly maintenanceMode: boolean;
     setLanguage(code: string): void;
     getLanguage(): string;
     setAuthToken(token: string): void;
     clearAuthToken(): void;
+    /**
+     * Change which storefront this client speaks for. Takes effect on the next
+     * request. Pass `null` to stop sending the header entirely (legacy,
+     * unscoped behaviour) — which is not the same as `'CONSUMER'`.
+     */
     setOrderScope(scope: OrderScope | null): void;
+    /** The scope currently sent as `x-order-scope`, or `null` when none is set. */
     getOrderScope(): OrderScope | null;
     graphql<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<T>;
 }