@sixtyninecommerce/client 0.31.0 → 0.33.0

package/dist/types.d.ts

@@ -120,18 +120,39 @@ export interface StorefrontClientConfig {
      * checkout for 15 minutes. Anything else is refused with `AGENT_SESSION_SCOPE`.
      */
     customerToken?: string;
-    /** Called when an auth token is received from Vendure (e.g. after login). Use to persist the token. */
+    /**
+     * Called when Vendure hands the client a new session token (a sign-in, or a
+     * new anonymous session for a guest or a dead token). Use to persist it.
+     *
+     * Only for a token that replaces the one the client holds now: a call
+     * answered after its token was replaced (a sign-in, `logout`, `setAuthToken`
+     * landed while it was in flight) has its token dropped, so a late answer
+     * never signs the newer session out. A sign-in's own token always applies.
+     */
     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.
+     * Called when a SIGNED-IN customer's session is gone: a Shop API call failed
+     * with UNAUTHORIZED, or with FORBIDDEN and a follow-up `activeCustomer` probe
+     * answered no customer. Vendure's Shop API returns FORBIDDEN both for a lost
+     * session and for a real authorization denial, so the probe is what tells
+     * them apart. Fires once per lost session. Use to prompt re-login or clear
+     * local user state.
+     *
+     * "Signed in" is what this client SAW: a successful `login`, `authenticate`,
+     * `loginWithMagicLink`, `loginWithMagicCode`, `verifyAccount` or
+     * `resetPassword`, or a `getCurrentCustomer()` that returned a customer.
+     * It never fires for a guest: a guest is refused with FORBIDDEN legitimately
+     * (an order placed in another browser, or past its guest read window), and
+     * its session — and cart — is still alive. A token handed in by
+     * `setAuthToken` or `customerToken` counts as signed in only once
+     * `getCurrentCustomer()` returns a customer for it, so a storefront that
+     * restores a stored token and wants this callback reads the customer first.
+     * `logout`, `setAuthToken` and `clearAuthToken` reset it.
+     *
+     * A FORBIDDEN with a still-signed-in 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.
+     * Earlier releases also fired it for a guest's FORBIDDEN.
      */
     onAuthExpired?: () => void;
     /**
@@ -465,6 +486,21 @@ export interface StoreContext {
     /** Channel tax-display storage mode — see {@link ChannelInfo.pricesIncludeTax}. */
     pricesIncludeTax: boolean;
     authToken: string | null;
+    /**
+     * `true` while the client knows `authToken` is a SIGNED-IN customer's
+     * session: a sign-in through this client succeeded, or an `activeCustomer`
+     * read answered a customer. Absent for a token the client never saw signed
+     * in (a guest's cart session, or one handed in by `setAuthToken` /
+     * `customerToken`); `false` once the server answered no customer. Gates
+     * `onAuthExpired`. Treat as internal.
+     */
+    customerSession?: boolean;
+    /**
+     * Bumped on every change to `customerSession` (`core/customer-session.ts`),
+     * so a response can tell whether the session it was sent for is still the
+     * one the client holds. Treat as internal.
+     */
+    customerSessionEpoch?: number;
     /**
      * Active order scope, emitted as the `x-order-scope` header. `null`/absent
      * means "send no header" — legacy, unscoped behaviour. See
@@ -575,7 +611,7 @@ export interface Asset {
  * `@sixtyninecommerce/client/pricing` does exactly that.
  */
 export type ProductAvailabilityState = Shop.ProductAvailabilityState;
-export type { AddItemInput, AdjustmentType, AuthenticationInput, BreadcrumbFragment, ChannelCustomFieldsFragment, CollectionDetailFragment, CollectionFragment, CollectionRefFragment, ConvertedAmountFragment, CreateAddressInput, CreateCustomerInput, CreateProductReviewInput, CreateQuoteRequestInput, CreditBalanceSource, CurrencyCode, CurrentUserFragment, CustomerPaymentTermsFragment, CustomerReturnFragment, CustomerSubscriptionFragment, DeliveryAdvice, DeliverySelectionSource, DeliveryTermsStatus, DepositPaymentIntentInput, FacetFragment, FacetValueFragment, FavoriteListOptions, LanguageCode, MolliePaymentIntentInput, MolliePaymentMethodsInput, MyPaymentMandateFragment, MyparcelDeliveryOptionsInput, MyparcelDropOffPointInput, NativeAuthInput, OrderDeliveryTermsFragment, OrderFragment, OrderFulfillmentParcelsFragment, OrderFulfillmentsFragment, OrderPaymentIntent, OrderPaymentTermsFragment, OrderReturnReasonCode, OrderReturnSettlementMethod, OrderReturnState, OrderSummaryFragment, OrderWritableCustomFieldsFragment, ParkedOrderFragment, ParkedOrderPaymentIntentInput, PayDepositInput, PaymentInput, PaymentTermsClassification, PaymentTermsStatus, PayParkedOrderInput, PickupLocationSearchInput, PlacementRejectionFragment, PriceTierFragment, ProductAvailabilityFragment, ProductCardFragment, ProductFragment, ProductMetadataFragment, ProductPropertyGroupValuesFragment, ProductReviewFragment, ProductReviewListOptions, ProductSummaryFragment, ProductVariantFragment, PropertyGroupFragment, PublicPaymentMethodFragment, PublicShippingMethodFragment, QuoteFragment, QuoteLegacyFragment, QuoteLineDiscountType, QuoteLineRequestInput, QuoteListOptions, QuoteStatus, RecentReviewsOptions, RecommendedProductGroupFragment, RegisterCustomerInput, RequestReturnInput, ReturnRequestLineInput, ReviewSortKey, ReviewStatus, SavedListFragment, SearchResultFragment, SearchResultItemFragment, SetupPaymentMandateInput, SubscriptionFirstChargeTiming, SubscriptionPlanPublicFragment, SubscriptionPurchaseResultFragment, UpdateAddressInput, UpdateCustomerInput, UpdateOrderCustomFieldsInput, UpdateProductReviewInput, VariantLocationAvailabilityFragment, VatValidationResultFragment, } from './generated/shop.js';
+export type { AddItemInput, AdjustmentType, AuthenticationInput, BreadcrumbFragment, ChannelCustomFieldsFragment, CollectionDetailFragment, CollectionFragment, CollectionRefFragment, ConvertedAmountFragment, CreateAddressInput, CreateCustomerInput, CreateProductReviewInput, CreateQuoteRequestInput, CreditBalanceSource, CurrencyCode, CurrentUserFragment, CustomerPaymentTermsFragment, CustomerReturnFragment, CustomerSubscriptionFragment, DeliveryAdvice, DeliverySelectionSource, DeliveryTermsStatus, DepositPaymentIntentInput, FacetFragment, FacetValueFragment, FavoriteListOptions, LanguageCode, MolliePaymentIntentInput, MolliePaymentMethodsInput, MyPaymentMandateFragment, MyparcelDeliveryOptionsInput, MyparcelDropOffPointInput, NativeAuthInput, OrderDeliveryTermsFragment, OrderFragment, OrderFulfillmentParcelsFragment, OrderFulfillmentsFragment, OrderMoneyBasis, OrderMoneyViewFragment, OrderPaymentIntent, OrderPaymentTermsFragment, OrderReturnReasonCode, OrderReturnSettlementMethod, OrderReturnState, OrderSummaryFragment, OrderWritableCustomFieldsFragment, ParkedOrderFragment, ParkedOrderPaymentIntentInput, PayDepositInput, PaymentInput, PaymentTermsClassification, PaymentTermsStatus, PayParkedOrderInput, PickupLocationSearchInput, PlacementRejectionFragment, PriceTierFragment, ProductAvailabilityFragment, ProductCardFragment, ProductFragment, ProductMetadataFragment, ProductPropertyGroupValuesFragment, ProductReviewFragment, ProductReviewListOptions, ProductSummaryFragment, ProductVariantFragment, PropertyGroupFragment, PublicPaymentMethodFragment, PublicShippingMethodFragment, QuoteFragment, QuoteLegacyFragment, QuoteLineDiscountType, QuoteLineRequestInput, QuoteListOptions, QuoteStatus, RecentReviewsOptions, RecommendedProductGroupFragment, RegisterCustomerInput, RequestReturnInput, ReturnRequestLineInput, ReviewSortKey, ReviewStatus, SavedListFragment, SearchResultFragment, SearchResultItemFragment, SetupPaymentMandateInput, SubscriptionFirstChargeTiming, SubscriptionPlanPublicFragment, SubscriptionPurchaseResultFragment, UpdateAddressInput, UpdateCustomerInput, UpdateOrderCustomFieldsInput, UpdateProductReviewInput, VariantLocationAvailabilityFragment, VatValidationResultFragment, } from './generated/shop.js';
 /** A strategy `commerce.authenticate` can sign in through: a member of the engine's `AuthenticationInput` (`native` today). */
 export type AuthenticationStrategy = keyof Shop.AuthenticationInput;
 /** What a strategy takes — `{ username, password }` for `native`. */
@@ -627,6 +663,18 @@ export type Product = Omit<Shop.ProductFragment, 'metadata'> & {
  *   sells (`lines` names them; the store stopped offering a product its
  *   organization shares). The buyer removes them. Adding one is refused with the
  *   same code.
+ * - `GIFT_CARD_LINE_FREE` — the cart holds a gift card priced at nothing
+ *   (`lines` names it). Gift cards are sold at their price.
+ * - `GIFT_CARD_ORDER_DISCOUNT` — money would come off an order that sells gift
+ *   cards: an order-wide coupon (`details` names it as `couponCode`) or a
+ *   discount. Gift cards are sold without discounts: the buyer removes the
+ *   coupon, or buys the gift cards in an order of their own.
+ * - `GIFT_CARD_NEEDS_BUYER_EMAIL` — the order sells gift cards, whose codes are
+ *   sent only by email, and its customer has no address that can receive one.
+ *   The buyer gives a real email address and places again.
+ * - `GIFT_CARD_NOT_FOR_SALE` — the cart holds a gift card, and the store sells
+ *   none now (`lines` names the card lines). The buyer removes them. Adding a
+ *   gift card, or raising its quantity, is refused with the same code.
  */
 export type PlacementRejectionCode = Shop.PlacementRejectionCode;
 /**
@@ -897,7 +945,21 @@ export interface CollectionListOptions {
 export interface OrderListOptions {
     take?: number;
     skip?: number;
+    /**
+     * Also read each order's money view (`Order.moneyView`) in `basis` (default `CUSTOMER`), so
+     * the list prints the same total as the order page: `item.moneyView.total`. `null` on an
+     * engine before the field (print `totalWithTax` as before).
+     */
+    moneyView?: {
+        basis?: Shop.OrderMoneyBasis;
+    };
 }
+/** An order-history page with each order's money view. */
+export type CustomerOrdersWithMoneyView = MergedSelection<NonNullable<Shop.CustomerOrdersQuery['activeCustomer']>['orders']> & {
+    items: Array<MergedSelection<NonNullable<Shop.CustomerOrdersQuery['activeCustomer']>['orders']['items'][number]> & {
+        moneyView: Shop.OrderMoneyViewFragment | null;
+    }>;
+};
 /** A "back in stock" subscription, as `subscribeToStockNotification` returns it. */
 export interface StockNotificationSubscriptionResult {
     id: string;
@@ -1203,6 +1265,21 @@ export type QuoteLine = Shop.QuoteLegacyFragment['lines'][number] & Partial<Omit
 export type Quote = Omit<Shop.QuoteFragment, 'lines'> & {
     lines: QuoteLine[];
 };
+/**
+ * The money on a held order as either parked-order document answers it. `creditNoted` (what the
+ * order's credit notes took off what it bills) and `owed` (what is left to pay after them: the
+ * most a payment may take, and what an omitted amount pays) are `undefined` against an engine
+ * before them, which caps a payment at `outstanding`: read `owed ?? outstanding`.
+ */
+export type ParkedOrderPosition = Shop.ParkedOrderLegacyFragment['position'] & Partial<Pick<Shop.ParkedOrderFragment['position'], 'creditNoted' | 'owed'>>;
+/** A held order as `getParkedOrders` answers it — see {@link ParkedOrderPosition}. */
+export type ParkedOrder = Omit<Shop.ParkedOrderFragment, 'position'> & {
+    position: ParkedOrderPosition;
+};
+/** What `payParkedOrder` answers — see {@link ParkedOrderPosition}. */
+export type ParkedOrderPaymentResult = Omit<Shop.PayParkedOrderMutation['payParkedOrder'], 'position'> & {
+    position: ParkedOrderPosition;
+};
 /** One page of `getMyQuotes`. */
 export type QuoteList = Omit<Shop.MyQuotesQuery['myQuotes'], 'items'> & {
     items: Quote[];
@@ -1371,6 +1448,11 @@ export interface CommerceModule {
      * released on or after 2026-10-05) when the store no longer sells the product;
      * so are `addItemsToCart` (the whole call) and `updateCartLine` raising such a
      * line. Lowering or removing a line always works.
+     *
+     * Refused with `StorefrontError` `ORDER_LINE_VARIANT_UNPRICED` (422, an engine
+     * released on or after 2026-10-10) when the store has no price for the product
+     * (`extensions.productVariantIds` names it); the same for `addItemsToCart` and
+     * `updateCartLine` raising such a line. Nothing is added.
      */
     addToCart(variantId: string, quantity: number): Promise<Shop.OrderFragment>;
     /** Add several variants in one call (e.g. favourite-box bundles). */
@@ -1721,9 +1803,15 @@ export interface CommerceModule {
      * 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`.
+     * order matches `orderCode`. Answered by the same rule as
+     * {@link CommerceModule.getOrderByCode}: pass `{ accessKey }` (the order's
+     * access key from the return URL) when the shopper may be back in another
+     * browser; the key only lets the order be READ, the sync itself only lands
+     * what Mollie reports paid.
+     *
+     * @effect write
      */
-    syncMolliePaymentStatus(orderCode: string, options?: RequestOptions): Promise<Shop.SyncMolliePaymentStatusMutation['syncMolliePaymentStatus']>;
+    syncMolliePaymentStatus(orderCode: string, options?: RequestOptions & import('./commerce/order-access-key.js').OrderAccessKeyOption): Promise<Shop.SyncMolliePaymentStatusMutation['syncMolliePaymentStatus']>;
     /**
      * Orders the store is currently HOLDING for the signed-in shopper.
      *
@@ -1735,8 +1823,13 @@ export interface CommerceModule {
      * An order the store is REVIEWING after the shopper paid it (an app the store
      * uses could not confirm it) is left out until the store accepts it: nothing
      * can be paid on it before then.
+     *
+     * Each `position` says what is left to pay as `owed`: on an order whose
+     * invoice a credit note lowered it is less than `outstanding`, which still
+     * counts the credited part. Against an engine before it, `owed` is absent
+     * (that engine takes up to `outstanding`).
      */
-    getParkedOrders(options?: RequestOptions): Promise<Shop.ParkedOrderFragment[]>;
+    getParkedOrders(options?: RequestOptions): Promise<ParkedOrder[]>;
     /**
      * Pay some or all of what a held order still owes. Requires a signed-in
      * customer, and the order must be theirs.
@@ -1752,6 +1845,10 @@ export interface CommerceModule {
      * card method is refused `PAYMENT_METHOD_UNUSABLE_HERE`; use
      * {@link CommerceModule.createParkedOrderPaymentIntent} for a card.
      *
+     * An omitted `amount` pays what the order still owes (`position.owed`); more
+     * than that is refused `AMOUNT_EXCEEDS_OUTSTANDING`, its message naming the
+     * credit notes when they lowered it.
+     *
      * Pass `idempotencyKey` for anything a shopper can double-tap: a repeat under
      * the same key returns the first payment instead of taking the money twice.
      *
@@ -1762,11 +1859,11 @@ export interface CommerceModule {
      */
     payParkedOrder(orderCode: string, input: Shop.PayParkedOrderInput, options?: RequestOptions & {
         idempotencyKey?: string;
-    }): Promise<Shop.PayParkedOrderMutation['payParkedOrder']>;
+    }): Promise<ParkedOrderPaymentResult>;
     /**
-     * Open a CARD payment for one of the signed-in shopper's held orders, for the
-     * whole outstanding balance (or, where the store takes deposits, part of it),
-     * and send the shopper to the returned `url`.
+     * Open a CARD payment for one of the signed-in shopper's held orders, for
+     * what it still owes (`position.owed`, or, where the store takes deposits,
+     * part of it), and send the shopper to the returned `url`.
      *
      * Nothing is paid by this call and the order does not change: the money is
      * recorded on the order when the provider confirms it, and the order leaves
@@ -1783,6 +1880,14 @@ export interface CommerceModule {
     createParkedOrderPaymentIntent(orderCode: string, input: Shop.ParkedOrderPaymentIntentInput, options?: RequestOptions & {
         idempotencyKey?: string;
     }): Promise<Shop.CreateParkedOrderPaymentIntentMutation['createParkedOrderPaymentIntent']>;
+    /**
+     * Sign in with email and password. An imported account without a password
+     * answers `password_reset_required`, an unverified one `account_not_verified`;
+     * a wrong password throws `INVALID_CREDENTIALS_ERROR`. A success marks the
+     * client signed in, so a later lost session fires `onAuthExpired`.
+     *
+     * @effect write
+     */
     login(email: string, password: string): Promise<LoginResult>;
     /**
      * Sign in through a named authentication strategy — the general form of
@@ -1802,6 +1907,11 @@ export interface CommerceModule {
      * whose lifetime the engine's session duration decides. A blank `strategy`
      * or an `input` that is not an object throws a 400 `INVALID_ARGUMENT` before
      * any request.
+     *
+     * A success marks the client signed in, so a later lost session fires
+     * `onAuthExpired`.
+     *
+     * @effect write
      */
     authenticate<S extends AuthenticationStrategy>(strategy: S, input: AuthenticationStrategyInput<S>, options?: RequestOptions & {
         rememberMe?: boolean;
@@ -1809,7 +1919,22 @@ export interface CommerceModule {
     register(input: Shop.RegisterCustomerInput): Promise<{
         success: boolean;
     }>;
+    /**
+     * End the session: clears the token, fires `onAuthCleared`, and forgets that
+     * the client was signed in (no `onAuthExpired` follows).
+     *
+     * @effect write
+     */
     logout(): Promise<void>;
+    /**
+     * The signed-in customer, or `null` for a guest or a session that lost its
+     * sign-in. Also teaches the client which one its token is: a customer makes
+     * a later lost session fire `onAuthExpired`, `null` does not. A storefront
+     * that restores a stored token with `setAuthToken` reads this first when it
+     * wants that callback.
+     *
+     * @effect read
+     */
     getCurrentCustomer(): Promise<Shop.MeQuery['activeCustomer']>;
     /**
      * Price lists currently applying to the signed-in customer (identity only,
@@ -1821,8 +1946,47 @@ export interface CommerceModule {
      * The signed-in customer's placed orders, newest first: the order-history rows
      * with each line's `backorderedQuantity` and every parcel's barcode
      * (`fulfillments[].trackingCodes`). An empty page for an anonymous visitor.
+     * `{ moneyView: { basis } }` adds each order's money view (see {@link OrderListOptions}).
+     *
+     * @effect read
+     */
+    getCustomerOrders(options: OrderListOptions & {
+        moneyView: {
+            basis?: Shop.OrderMoneyBasis;
+        };
+    }): Promise<CustomerOrdersWithMoneyView>;
+    getCustomerOrders(options?: OrderListOptions & {
+        moneyView?: undefined;
+    }): Promise<MergedSelection<NonNullable<Shop.CustomerOrdersQuery['activeCustomer']>['orders']>>;
+    getCustomerOrders(options?: OrderListOptions): Promise<MergedSelection<NonNullable<Shop.CustomerOrdersQuery['activeCustomer']>['orders']> | CustomerOrdersWithMoneyView>;
+    /**
+     * The order's money as the engine prints it on the dashboard, in emails and on invoices: rows
+     * that add up exactly to the order's own totals, in `options.basis` (default `CUSTOMER`: how
+     * the shop shows prices to that customer). `'active'` is the shopper's cart; `{ code }` a
+     * placed order the shopper may read (as `getOrderByCode`, else `NOT_FOUND`, 404). Print it
+     * with `orderMoneyRows(view)`; never add the figures up yourself.
+     *
+     * Resolves `null` when there is nothing to print from: no active order, or an engine before
+     * `Order.moneyView` (print the order's own fields as before). Refused before sending:
+     * `INVALID_ORDER_MONEY_BASIS` and `INVALID_ORDER_MONEY_TARGET` (400), and a
+     * blank `accessKey` (`INVALID_ARGUMENT`). `{ accessKey }` reads a `{ code }`
+     * order as {@link CommerceModule.getOrderByCode} does.
+     *
+     * @effect read
      */
-    getCustomerOrders(options?: OrderListOptions): Promise<MergedSelection<NonNullable<Shop.CustomerOrdersQuery['activeCustomer']>['orders']>>;
+    getOrderMoneyView(order: import('./commerce/money-view.js').OrderMoneyViewTarget, options?: RequestOptions & import('./commerce/order-access-key.js').OrderAccessKeyOption & {
+        basis?: Shop.OrderMoneyBasis;
+    }): Promise<Shop.OrderMoneyViewFragment | null>;
+    /**
+     * The cart's private access key (`Order.accessKey`), to put in the payment
+     * return URL so the confirmation page can read the order in whatever browser
+     * the shopper comes back in: `getOrderByCode(code, { accessKey })`. `null`
+     * with no cart, no keys configured on the engine, or an engine before the
+     * field. A secret of the shopper's: never log it or send it to analytics.
+     *
+     * @effect read
+     */
+    getActiveOrderAccessKey(options?: RequestOptions): Promise<string | null>;
     /**
      * 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
@@ -1872,9 +2036,23 @@ export interface CommerceModule {
      */
     setPassword(newPassword: string): Promise<void>;
     requestPasswordReset(emailAddress: string): Promise<void>;
+    /**
+     * Set a new password from a reset token and sign in.
+     * A success marks the client signed in, so a later lost session fires
+     * `onAuthExpired`.
+     *
+     * @effect write
+     */
     resetPassword(token: string, password: string): Promise<Shop.CurrentUserFragment>;
     requestEmailUpdate(password: string, newEmailAddress: string): Promise<void>;
     updateEmail(token: string): Promise<void>;
+    /**
+     * Verify the account from its emailed token and sign in.
+     * A success marks the client signed in, so a later lost session fires
+     * `onAuthExpired`.
+     *
+     * @effect write
+     */
     verifyAccount(token: string, password?: string): Promise<Shop.CurrentUserFragment>;
     refreshVerification(emailAddress: string): Promise<void>;
     /**
@@ -1886,7 +2064,21 @@ export interface CommerceModule {
      * credential limiter does. Neither reveals whether the account exists.
      */
     requestMagicLink(emailAddress: string, options?: RequestMagicLinkOptions): Promise<void>;
+    /**
+     * Sign in with the emailed link's token.
+     * A success marks the client signed in, so a later lost session fires
+     * `onAuthExpired`.
+     *
+     * @effect write
+     */
     loginWithMagicLink(token: string): Promise<Shop.CurrentUserFragment>;
+    /**
+     * Sign in with the emailed 6-digit code.
+     * A success marks the client signed in, so a later lost session fires
+     * `onAuthExpired`.
+     *
+     * @effect write
+     */
     loginWithMagicCode(emailAddress: string, code: string): Promise<Shop.CurrentUserFragment>;
     createAddress(input: Shop.CreateAddressInput): Promise<Shop.CreateAddressMutation['createCustomerAddress']>;
     updateAddress(input: Shop.UpdateAddressInput): Promise<Shop.UpdateAddressMutation['updateCustomerAddress']>;
@@ -1896,10 +2088,32 @@ export interface CommerceModule {
      * One of the shopper's orders by code — the cart selection plus what a placed
      * order carries: `lines[].backorderedQuantity`, `customFields.chargedParcelCount`,
      * the fulfilments with every parcel's barcode, the external shipments and the
-     * payment and delivery terms frozen at acceptance. Throws a `NOT_FOUND`
-     * `StorefrontError` (404) when there is none.
-     */
-    getOrderByCode(code: string): Promise<MergedSelection<NonNullable<Shop.OrderByCodeQuery['orderByCode']>>>;
+     * payment and delivery terms frozen at acceptance.
+     *
+     * Answered only to the signed-in customer whose order it is, or to the guest
+     * session that put the order together (the client's own session token), for
+     * as long as that session lives: there is no limit on the order's age. The
+     * platform drops a guest session after a year, or once it has held no cart for
+     * 7 days; a storefront that loses or clears the token loses it too. Anyone
+     * else, another browser of the same guest or a later session of the same
+     * browser included, gets a `FORBIDDEN` `StorefrontError` (403), and so does a
+     * code that names no order: the server never tells the two apart. (`NOT_FOUND`
+     * is thrown only if the server answers no order without an error.) A
+     * confirmation page shows a "thank you, order {code} received, the details are
+     * in your email" fallback on `FORBIDDEN`, never the order's contents. A
+     * guest's `FORBIDDEN` here never fires `onAuthExpired`: its session is alive.
+     *
+     * `{ accessKey }`: the order's private access key (the `key` of the order
+     * email's "view your order" link, or `getActiveOrderAccessKey()` put in the
+     * return URL). With it a client with NO sign-in reads this one order in any
+     * browser, for as long as the order exists; a signed-in client's login
+     * decides instead, so sign-in-aware pages send it from an anonymous client.
+     * A wrong or foreign key is the same `FORBIDDEN`. A blank one is refused
+     * before sending (`INVALID_ARGUMENT`).
+     *
+     * @effect read
+     */
+    getOrderByCode(code: string, options?: import('./commerce/order-access-key.js').OrderAccessKeyOption): Promise<MergedSelection<NonNullable<Shop.OrderByCodeQuery['orderByCode']>>>;
     /** Invoices for one of the signed-in customer's own orders. */
     getMyOrderInvoices(orderCode: string): Promise<Shop.MyOrderInvoicesQuery['myOrderInvoices']>;
     /** Download one of the signed-in customer's own invoices as a base64 PDF. */
@@ -1937,9 +2151,27 @@ export interface CommerceModule {
     subscribeToStockNotification(productVariantId: string, emailAddress?: string): Promise<StockNotificationSubscriptionResult>;
     unsubscribeFromStockNotification(token: string): Promise<boolean>;
     getProductRecommendations(productId: string, groupSlug?: string): Promise<Shop.RecommendedProductGroupFragment[]>;
+    /** The shops that offer pickup, each with `available` for the active order (never a quantity). */
+    getStorePickupLocations(): Promise<Shop.StorePickupLocationFragment[]>;
+    /** The active order's store pickup: the chosen shop, then the pickup's state once placed. */
+    getActiveOrderStorePickup(): Promise<NonNullable<Shop.ActiveOrderStorePickupQuery['activeOrder']>['storePickup'] | null>;
+    /**
+     * Collect the active order at a shop: names it (the shipping address becomes the shop's), then
+     * selects the store-pickup method. `STORE_PICKUP_METHOD_UNAVAILABLE` when the method is not
+     * eligible (the shop is short of an item, or the store has none).
+     */
+    chooseStorePickup(stockLocationId: string): Promise<Shop.OrderFragment>;
+    /** Stop collecting at a shop (call it before the shopper's own address and method). */
+    clearStorePickup(): Promise<Shop.OrderFragment>;
     getAgeVerificationStatus(): Promise<Shop.AgeVerificationStatusQuery['ageVerificationStatus']>;
     submitDateOfBirth(dateOfBirth: string): Promise<Shop.SubmitDateOfBirthMutation['submitDateOfBirth']>;
     confirmAge(): Promise<Shop.ConfirmAgeMutation['confirmAge']>;
+    /**
+     * Add a till purchase to the signed-in shopper's account with the token of its receipt link
+     * (read it with `receiptClaimTokenFrom(window.location)`). `alreadyYours` when it already was.
+     * Every refusal is `POS_RECEIPT_CLAIM_NOT_FOUND`; a guest is `FORBIDDEN`.
+     */
+    claimReceipt(token: string): Promise<Shop.ClaimPosReceiptMutation['claimPosReceipt']>;
     getProductReviews(productId: string, options?: Shop.ProductReviewListOptions): Promise<Shop.ProductReviewsQuery['productReviews']>;
     getRecentProductReviews(options?: Shop.RecentReviewsOptions): Promise<Shop.ProductReviewFragment[]>;
     getReviewRatingSummary(productId: string): Promise<Shop.ProductRatingSummaryQuery['productRatingSummary']>;
@@ -1953,24 +2185,83 @@ export interface CommerceModule {
     voteReview(reviewId: string, isHelpful: boolean): Promise<boolean>;
     reportReview(reviewId: string, reason: string): Promise<boolean>;
     uploadReviewMedia(files: File[]): Promise<Shop.UploadReviewMediaMutation['uploadReviewMedia']>;
+    /**
+     * Refusals: `FORBIDDEN` (signed out), `SUBSCRIPTION_GUEST_NOT_ALLOWED` (no customer in this
+     * store), `SUBSCRIPTION_NOT_FOUND` (not the customer's, or not in this store).
+     */
     getMySubscription(id: string): Promise<Shop.CustomerSubscriptionFragment | null>;
+    /**
+     * Refusals: `SUBSCRIPTION_PLAN_UNAVAILABLE`, `SUBSCRIPTION_MANDATE_UNAVAILABLE`,
+     * `SUBSCRIPTION_GUEST_NOT_ALLOWED` (a `mandateId` while signed out), and what stops the store
+     * billing the plan (`SUBSCRIPTION_PRODUCT_UNAVAILABLE`, `SUBSCRIPTION_SHIPPING_UNAVAILABLE`,
+     * `SUBSCRIPTION_CURRENCY_NOT_AVAILABLE`).
+     */
     previewSubscriptionPurchase(planId: string, options?: {
         provider?: 'mollie' | 'stripe';
         mandateId?: string;
     }): Promise<Shop.SubscriptionPurchasePreviewQuery['subscriptionPurchasePreview']>;
+    /**
+     * Refusals, each before any payment starts: `SUBSCRIPTION_PREVIEW_CONFLICT` (the price changed
+     * since the preview: preview again and confirm again), `SUBSCRIPTION_REQUEST_KEY_CONFLICT` (the
+     * key belongs to another action), `SUBSCRIPTION_REQUEST_KEY_INVALID`,
+     * `SUBSCRIPTION_RETURN_URL_INVALID`, `SUBSCRIPTION_INPUT_INVALID` (no or an unknown provider),
+     * `SUBSCRIPTION_PLAN_UNAVAILABLE`, `SUBSCRIPTION_MANDATE_UNAVAILABLE`,
+     * `SUBSCRIPTION_AMOUNT_UNREPRESENTABLE`, the order the store cannot build
+     * (`SUBSCRIPTION_ADDRESS_REQUIRED`, `SUBSCRIPTION_PRODUCT_UNAVAILABLE`,
+     * `SUBSCRIPTION_SHIPPING_UNAVAILABLE`, `SUBSCRIPTION_STOCK_INSUFFICIENT`,
+     * `SUBSCRIPTION_ORDER_REFUSED`), `FORBIDDEN` (signed out) and `SUBSCRIPTION_GUEST_NOT_ALLOWED`
+     * (no customer in this store).
+     */
     startSubscriptionPurchase(input: SubscriptionPurchaseInput): Promise<Shop.SubscriptionPurchaseResultFragment>;
+    /**
+     * Refusals: `SUBSCRIPTION_PURCHASE_NOT_FOUND`, `FORBIDDEN` (signed out),
+     * `SUBSCRIPTION_GUEST_NOT_ALLOWED` (no customer in this store).
+     */
     getSubscriptionPurchaseStatus(id: string): Promise<Shop.SubscriptionPurchaseResultFragment>;
+    /**
+     * Refusals: `SUBSCRIPTION_NOT_FOUND`, `FORBIDDEN` (signed out),
+     * `SUBSCRIPTION_GUEST_NOT_ALLOWED` (no customer in this store),
+     * `SUBSCRIPTION_INPUT_INVALID` (an action the storefront may not ask for). A change that is not
+     * possible now is not refused here: it answers `allowed: false` with its `reason`.
+     */
     previewMySubscriptionChange(id: string, input: SubscriptionLifecycleCommand): Promise<Shop.PreviewMySubscriptionChangeQuery['previewMySubscriptionChange']>;
+    /**
+     * Refusals (also of `skipMySubscription`, `rescheduleMySubscription`,
+     * `undoMySubscriptionCancellation`): `SUBSCRIPTION_NOT_FOUND`, `FORBIDDEN` (signed out),
+     * `SUBSCRIPTION_GUEST_NOT_ALLOWED` (no customer in this store),
+     * `SUBSCRIPTION_OVERRIDE_NOT_ALLOWED` (a staff-only option), `SUBSCRIPTION_INPUT_INVALID`,
+     * `SUBSCRIPTION_DATE_INVALID`, `SUBSCRIPTION_REQUEST_KEY_CONFLICT` /
+     * `SUBSCRIPTION_REQUEST_KEY_INVALID`, and the change not possible now:
+     * `SUBSCRIPTION_CHANGE_CUTOFF_PASSED`, `SUBSCRIPTION_CYCLE_UNRESOLVED`,
+     * `SUBSCRIPTION_STATUS_BLOCKS_CHANGE`, `SUBSCRIPTION_AWAITING_PAYMENT_METHOD`,
+     * `SUBSCRIPTION_CANCELLATION_EFFECTIVE`, `SUBSCRIPTION_NO_NEXT_RENEWAL` (re-read the
+     * subscription and show its `allowedActions`).
+     */
     manageMySubscription(id: string, input: SubscriptionLifecycleCommand): Promise<Shop.CustomerSubscriptionFragment>;
     skipMySubscription(id: string, requestKey: string): Promise<Shop.CustomerSubscriptionFragment>;
     rescheduleMySubscription(id: string, date: string, requestKey: string): Promise<Shop.CustomerSubscriptionFragment>;
     undoMySubscriptionCancellation(id: string, requestKey: string): Promise<Shop.CustomerSubscriptionFragment>;
+    /**
+     * Refusals: `SUBSCRIPTION_NOT_FOUND`, `FORBIDDEN` (signed out),
+     * `SUBSCRIPTION_GUEST_NOT_ALLOWED` (no customer in this store),
+     * `SUBSCRIPTION_INPUT_INVALID` (no or an unknown provider), `SUBSCRIPTION_RETURN_URL_INVALID`,
+     * `SUBSCRIPTION_REQUEST_KEY_CONFLICT` / `SUBSCRIPTION_REQUEST_KEY_INVALID`,
+     * `SUBSCRIPTION_STATUS_BLOCKS_CHANGE`, `SUBSCRIPTION_PAYMENT_UNRESOLVED` (a setup is still open).
+     */
     replaceMySubscriptionMandate(id: string, input: SubscriptionPaymentActionInput & {
         provider: 'mollie' | 'stripe';
     }): Promise<Shop.SubscriptionPurchaseResultFragment>;
     /**
      * A hosted link that pays the outstanding failed or charged-back cycle again,
      * without another delivery. Reuse `upcomingPayment.checkoutUrl` while it is live.
+     *
+     * Refusals: `SUBSCRIPTION_NOT_FOUND`, `FORBIDDEN` (signed out),
+     * `SUBSCRIPTION_GUEST_NOT_ALLOWED` (no customer in this store),
+     * `SUBSCRIPTION_RETURN_URL_INVALID`, `SUBSCRIPTION_REQUEST_KEY_CONFLICT` /
+     * `SUBSCRIPTION_REQUEST_KEY_INVALID`, `SUBSCRIPTION_STATUS_BLOCKS_CHANGE`,
+     * `SUBSCRIPTION_PAYMENT_UNRESOLVED` (the previous payment is not definitively over),
+     * `SUBSCRIPTION_CYCLE_PAYMENT_HELD` (the store must reconcile a payment it holds),
+     * `SUBSCRIPTION_AMOUNT_UNREPRESENTABLE`.
      */
     recoverMySubscriptionPayment(id: string, input: SubscriptionPaymentActionInput): Promise<Shop.SubscriptionPurchaseResultFragment>;
     getMySubscriptions(): Promise<Shop.CustomerSubscriptionFragment[]>;
@@ -1987,14 +2278,26 @@ export interface CommerceModule {
     /**
      * Begin establishing a payment mandate. Returns a `checkoutUrl` (Mollie) or
      * `clientSecret` (Stripe) for the frontend to complete the setup.
+     *
+     * Refusals: `FORBIDDEN` (signed out), `SUBSCRIPTION_RETURN_URL_INVALID` (`redirectUrl`),
+     * `SUBSCRIPTION_INPUT_INVALID` (an unknown provider).
      */
     setupPaymentMandate(input: Shop.SetupPaymentMandateInput): Promise<Shop.SetupPaymentMandateMutation['setupPaymentMandate']>;
     /**
      * Create a subscription for the active customer against an enabled plan
      * using one of their valid mandates.
+     *
+     * Refusals: `FORBIDDEN` (signed out, or another customer's mandate),
+     * `SUBSCRIPTION_MANDATE_NOT_FOUND`, `SUBSCRIPTION_MANDATE_NOT_VALID` (not verified yet),
+     * `SUBSCRIPTION_PLAN_UNAVAILABLE`, and `startSubscriptionPurchase`'s order and request-key
+     * refusals.
      */
     createSubscription(planId: string, mandateId: string, requestKey?: string): Promise<Shop.CustomerSubscriptionFragment>;
-    /** Pause an active or trial subscription owned by the active customer. */
+    /**
+     * Pause an active or trial subscription owned by the active customer. Refusals (also of
+     * `resumeMySubscription` and `cancelMySubscription`): `FORBIDDEN` (signed out, or another
+     * customer's), `SUBSCRIPTION_NOT_FOUND`, and `manageMySubscription`'s "not possible now" codes.
+     */
     pauseMySubscription(id: string, reason?: string): Promise<Shop.CustomerSubscriptionFragment>;
     /** Resume a paused subscription owned by the active customer. */
     resumeMySubscription(id: string): Promise<Shop.CustomerSubscriptionFragment>;
@@ -2056,8 +2359,15 @@ export interface CommerceModule {
      * 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.
+     *
+     * A unit an invoice correction already credited is not returnable: each
+     * line says how many (`creditedQty`) and on which credit notes
+     * (`correctionCredits`), so the UI can say "1 already credited on
+     * CN-00053"; `requestReturn` refuses more with
+     * `RETURN_QUANTITY_ALREADY_CREDITED`. Needs a vendure-server that serves
+     * those fields.
      */
-    getReturnableLinesForOrder(orderId: string): Promise<Shop.ReturnableLinesForOrderQuery['returnableLinesForOrder']>;
+    getReturnableLinesForOrder(orderId: string): Promise<ReturnableLinesForOrder>;
     getMyVatValidationStatus(): Promise<Shop.VatValidationResultFragment | null>;
     setMyVatNumber(vatNumber: string): Promise<Shop.VatValidationResultFragment>;
     clearMyVatNumber(): Promise<boolean>;
@@ -2237,6 +2547,9 @@ export interface PricingModule {
      * lines' gross total (`subTotalWithTax`, no shipping), the net minimum and
      * the delivery minimum (`fulfillmentMinOrderNet`, skipped for an exempt
      * customer) against the lines' net total (`subTotal`), and the item count.
+     * The gross and net minimums are judged before a price-list order-rule
+     * discount ("Order discount"), as the engine judges them, when the order
+     * carries its `discounts` and `promotions` (as `OrderFragment` does).
      *
      * Amounts are formatted in `constraints.currencyCode` and compared only with
      * an order in that currency; when the two differ (constraints fetched before
@@ -2262,6 +2575,23 @@ export interface PricingModule {
          */
         subTotal?: number;
         total?: number;
+        /**
+         * The order's discounts (`Order.discounts`). With `promotions`, the
+         * price-list order-rule discount is added back before the gross and net
+         * minimums are compared.
+         */
+        discounts?: ReadonlyArray<{
+            adjustmentSource: string;
+            amount: number;
+            amountWithTax: number;
+        }>;
+        /** The order's promotions with their condition codes (`OrderFragment.promotions`). */
+        promotions?: ReadonlyArray<{
+            id: string;
+            conditions?: ReadonlyArray<{
+                code: string;
+            }> | null;
+        }>;
     }, constraints: {
         minOrderAmountGross?: number | null;
         minOrderAmountNet?: number | null;
@@ -2404,7 +2734,15 @@ export interface StorefrontClient {
     readonly maintenanceMode: boolean;
     setLanguage(code: string): void;
     getLanguage(): string;
+    /**
+     * Send this session token on every Shop API call (a token restored from a
+     * cookie or storage). The client cannot tell a guest's token from a
+     * customer's, so it does not count as signed in — and `onAuthExpired` does
+     * not fire for it — until `commerce.getCurrentCustomer()` returns a customer
+     * or a sign-in succeeds.
+     */
     setAuthToken(token: string): void;
+    /** Stop sending a session token; the client is no longer signed in. */
     clearAuthToken(): void;
     /**
      * Change which storefront this client speaks for. Takes effect on the next
@@ -2434,4 +2772,14 @@ export interface StorefrontClient {
      */
     graphql<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<T>;
 }
+/** One line of {@link ReturnableLinesForOrder}. */
+export type ReturnableLineForOrder = Shop.ReturnableLinesForOrderLegacyQuery['returnableLinesForOrder']['lines'][number] & Partial<Pick<Shop.ReturnableLinesForOrderQuery['returnableLinesForOrder']['lines'][number], 'creditedQty' | 'correctionCredits'>>;
+/**
+ * What `getReturnableLinesForOrder` answers. `creditedQty` and `correctionCredits` are absent from
+ * an engine released before 2026-10-09, which does not subtract what an invoice correction
+ * credited.
+ */
+export type ReturnableLinesForOrder = Omit<Shop.ReturnableLinesForOrderLegacyQuery['returnableLinesForOrder'], 'lines'> & {
+    lines: ReturnableLineForOrder[];
+};
 //# sourceMappingURL=types.d.ts.map