@sixtyninecommerce/client 0.32.0 → 0.34.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`. */
@@ -636,6 +672,14 @@ export type Product = Omit<Shop.ProductFragment, 'metadata'> & {
  * - `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.
+ * - `VIEW_ONLY_ACCOUNT` — the signed-in account is view-only: it browses and
+ *   fills a basket but never places an order (the customer's `isViewOnly`).
+ *   Paying, opening a payment intent or mandate, and requesting or accepting a
+ *   quote are refused with the same code (the error's message is the buyer's
+ *   sentence). Show `customerMessage` and offer no checkout.
  */
 export type PlacementRejectionCode = Shop.PlacementRejectionCode;
 /**
@@ -906,7 +950,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;
@@ -1104,6 +1162,11 @@ export interface TaxDisplayInputs {
     countryCode: string | null;
     /** `Channel.pricesIncludeTax` — the STORAGE mode, not a display decision. */
     pricesIncludeTax: boolean;
+    /**
+     * Member of a "view only" customer group (`Customer.isViewOnly`): always
+     * shown gross, unless a listed country applies. Absent means false.
+     */
+    isViewOnly?: boolean;
 }
 /**
  * A resolved mode cached against the identity it was resolved for. Stored on
@@ -1212,6 +1275,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[];
@@ -1735,9 +1813,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.
      *
@@ -1749,8 +1833,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.
@@ -1766,6 +1855,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.
      *
@@ -1776,11 +1869,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
@@ -1797,6 +1890,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
@@ -1816,6 +1917,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;
@@ -1823,7 +1929,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,
@@ -1835,8 +1956,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
@@ -1886,9 +2046,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>;
     /**
@@ -1900,7 +2074,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']>;
@@ -1910,10 +2098,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. */
@@ -2534,7 +2744,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