@zenky/storefront-vue 0.10.8 → 0.10.9

package/dist/cart/index.d.ts

@@ -1,9 +1,9 @@
-import { ProductModifiersRequest, OrderProductVariant, PaymentMethod, OrderPaymentMethodRequest, OrderAuthenticationMethod, OrderCredentials, Order, OrderCheckoutTotal, OrderSettings, OrderPaymentMethod, OrderDeliveryMethod, InclusionRequest, ZenkyStorefront, SetOrderCustomerRequest, SetOrderDeliveryRequest, OrderPromocode, OrderCheckoutResult, RecaptchaAction, EvaluatedRestriction, Media, Product } from '@zenky/storefront-api';
+import { ProductModifiersRequest, OrderProductVariant, PaymentMethod, OrderPaymentMethodRequest, OrderAuthenticationMethod, OrderCredentials, Order, OrderCheckoutTotal, OrderSettings, OrderPaymentMethod, OrderDeliveryMethod, InclusionRequest, ZenkyStorefront, SetOrderCustomerRequest, SetOrderDeliveryRequest, OrderPromocode, RecommendationsBlock, OrderCheckoutResult, RecaptchaAction, EvaluatedRestriction, Media, Product } from '@zenky/storefront-api';
 import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
 import { ActivityReporter, Notifier, Result } from '../ports/index.js';
 import '@zenky/integrations-sdk';
 
-/** WebSocket события канала заказа */
+/** WebSocket events for the order channel */
 declare const ORDER_EVENTS: {
     readonly PriceRecalculated: "orders.price.recalculated";
     readonly Reload: "orders.reload";
@@ -14,7 +14,7 @@ declare const ORDER_EVENTS: {
     readonly RewardsReload: "orders.rewards.reload";
 };
 
-/** Нормализация строки адреса для сравнения (lowercase, схлопывание запятых/пробелов). */
+/** Normalizes an address string for comparison (lowercase, collapse commas/spaces). */
 declare function normalizeAddress(value: string | null | undefined): string;
 
 interface CartLineKeyParams {
@@ -23,7 +23,7 @@ interface CartLineKeyParams {
     promotionId?: string;
     promotionRewardId?: string;
 }
-/** Детерминированный ключ строки корзины: variant + sorted modifiers + promotion. */
+/** Deterministic cart line key: variant + sorted modifiers + promotion. */
 declare function buildCartLineKey(params: CartLineKeyParams): string;
 declare function variantLineKey(variant: OrderProductVariant): string;
 
@@ -35,167 +35,171 @@ interface MainPaymentRequestParams {
     currency: string;
 }
 /**
- * Основной (не-бонусный) payment-request из выбранного способа оплаты.
- * Единый источник для UI и reconciliation; `bill` конвертируется minor→major здесь.
+ * Builds the main (non-bonus) payment request from the selected payment method.
+ * Single source of truth for both UI and reconciliation; `bill` is converted
+ * minor → major here.
  */
 declare function buildMainPaymentRequest(params: MainPaymentRequestParams): OrderPaymentMethodRequest | null;
 
 /**
- * Утилиты для построения пресетов «с какой суммы приготовить сдачу» (cash bill)
- * в минорных единицах валюты (копейки/тыйны/сатанги).
+ * Utilities for building "prepare change from this amount" (cash bill) presets,
+ * in minor currency units (kopecks/tiyn/satang).
  *
- * UI отображает пресеты как пилюли: «1100 ₽», «1500 ₽», «5000 ₽» и т.п.
+ * The UI shows the presets as pills: "1100 ₽", "1500 ₽", "5000 ₽", etc.
  */
 /**
- * Номиналы банкнот по странам в **мажорных** единицах валюты.
- * Набор банкнот зависит от страны (рубли РФ ≠ тенге KZ), а конвертация
- * мажор → минор — от валюты (через `majorToMinor`, который сам учитывает
- * число дробных знаков по ISO-коду). Поэтому `getCashDenominationsMinor`
- * принимает и страну (выбор набора), и валюту (фактор конвертации).
+ * Banknote denominations per country, in **major** currency units.
+ * The set of banknotes depends on the country (RU rubles ≠ KZ tenge), while
+ * the major → minor conversion depends on the currency (via `majorToMinor`,
+ * which accounts for the number of decimal digits per ISO code). That's why
+ * `getCashDenominationsMinor` takes both a country (to pick the set) and a
+ * currency (the conversion factor).
  */
 declare const CASH_DENOMINATIONS_MAJOR: Record<string, number[]>;
 /**
- * Шаги округления вверх в **мажорных** единицах: 10 / 50 / 100 / 200 / 500 / 1000.
- * Конвертируются в минорные по валюте через `getDefaultRoundStepsMinor` —
- * чтобы работать для валют с любым числом дробных знаков, а не только ×100.
+ * Round-up steps in **major** units: 10 / 50 / 100 / 200 / 500 / 1000.
+ * Converted to minor units per currency via `getDefaultRoundStepsMinor` — so
+ * it works for currencies with any number of decimal digits, not just ×100.
  */
 declare const DEFAULT_ROUND_STEPS_MAJOR: readonly number[];
 declare function getDefaultRoundStepsMinor(currency?: string): number[];
-/** Номиналы в минорных единицах для страны магазина (с фолбэком на RU). */
 declare function getCashDenominationsMinor(country: string | null | undefined, currency?: string): number[];
 interface CashChangePresetsOptions {
-    /** Сумма заказа в минорных единицах. */
     totalMinor: number;
-    /** Номиналы банкнот в минорных единицах (см. `getCashDenominationsMinor`). */
+    /** Banknote denominations in minor units (see `getCashDenominationsMinor`). */
     denominationsMinor: number[];
-    /** Шаги округления — переопределяй только если знаешь зачем. */
+    /** Round-up steps — override this only if you know why. */
     roundStepsMinor?: readonly number[];
 }
 /**
- * Строит пресеты сдачи в минорных единицах:
- * объединяем округлённые вверх суммы (до 10/50/100/200/500/1000) и все
- * банкноты > total, дедупим, сортируем по возрастанию.
+ * Builds change presets in minor units: combines round-up sums (to
+ * 10/50/100/200/500/1000) with all banknotes > total, dedupes, and sorts
+ * ascending.
  *
- * Округления — strict (`total + 1`), чтобы сдача всегда была > 0.
+ * Rounding is strict (`total + 1`), so the change is always > 0.
  *
- * Примеры (для RU, total в рублях для краткости):
+ * Examples (for RU, total in rubles for brevity):
  *   total = 1080: 1090 / 1100 / 1200 / 1500 / 2000 / 5000 / 10000
  *   total = 1130: 1140 / 1150 / 1200 / 1500 / 2000 / 5000 / 10000
  *   total = 3060: 3070 / 3100 / 3200 / 3500 / 4000 / 5000 / 10000
  *   total = 3982: 3990 / 4000 / 5000 / 10000
- *   total = 0:    все банкноты как есть.
+ *   total = 0:    all banknotes as-is.
  */
 declare function buildCashChangePresets({ totalMinor, denominationsMinor, roundStepsMinor, }: CashChangePresetsOptions): number[];
 
 /**
- * Единый формат логов ошибок для всех cart/checkout-операций + извлечение
- * читаемых сообщений из ZenkyError для UI (toast / inline).
+ * Common error log format for all cart/checkout operations, plus extraction
+ * of readable messages from a ZenkyError for the UI (toast / inline).
  *
- * Контракт ошибок Zenky API (см. `ApiError` в SDK):
+ * Zenky API error contract (see `ApiError` in the SDK):
  *   {
  *     err: {
- *       message: string,             // локализованное — "Адрес доставки не указан."
- *       original_message: string,    // англ. оригинал
+ *       message: string,             // localized — "Адрес доставки не указан."
+ *       original_message: string,    // English original
  *       http_code: number,
  *       error_code: string,          // 'addresses.not_specified' | 'validation' | etc.
- *       meta: any,                   // для validation: { errors: { [field]: string[] } }
+ *       meta: any,                   // for validation: { errors: { [field]: string[] } }
  *     }
  *   }
  *
- * Для validation-ошибок (`error_code === 'validation'`) — берём сообщения из
- * `meta.errors`, не верхнеуровневое generic сообщение.
+ * For validation errors (`error_code === 'validation'`), we take the messages
+ * from `meta.errors` instead of the generic top-level message.
  */
 interface CartErrorScope {
-    /** Префикс — operation name (`cart-add` / `delivery` / `promocode-apply` / etc.) */
+    /** Prefix — operation name (`cart-add` / `delivery` / `promocode-apply` / etc.) */
     scope: string;
-    /** Параметры операции — id'шники, входы, что в данный момент в credentials */
+    /** Operation parameters — ids, inputs, whatever is currently in credentials */
     context?: Record<string, unknown>;
 }
 /**
- * Залогировать ошибку cart/checkout-операции в едином формате.
- * Безопасно для любого `unknown` — не падает на не-ZenkyError ошибках.
+ * Logs a cart/checkout operation error in a common format.
+ * Safe for any `unknown` value — doesn't throw on non-ZenkyError errors.
  */
 declare function logCartError({ scope, context }: CartErrorScope, e: unknown): void;
 /**
- * Достаёт `error_code` бэка (например `addresses.not_specified`).
- * Возвращает undefined для не-Zenky ошибок.
+ * Extracts the backend `error_code` (e.g. `addresses.not_specified`).
+ * Returns undefined for non-Zenky errors.
  */
 declare function getCartErrorCode(e: unknown): string | undefined;
 /**
- * Достаёт HTTP-код бэка (например 401 для требующей авторизации операции).
- * Возвращает undefined для не-Zenky ошибок.
+ * Extracts the backend HTTP code (e.g. 401 for an operation that requires
+ * authorization). Returns undefined for non-Zenky errors.
  */
 declare function getCartErrorHttpCode(e: unknown): number | undefined;
 /**
- * Достаёт field → [messages] из ZenkyError для валидации.
- * Возвращает {} если ошибка не validation или meta.errors пусто.
+ * Extracts field → [messages] from a ZenkyError for validation.
+ * Returns {} if the error isn't a validation error or meta.errors is empty.
  */
 declare function getValidationErrors(e: unknown): Record<string, string[]>;
 /**
- * Вытащить читаемое сообщение для UI (toast / inline).
+ * Extracts a readable message for the UI (toast / inline).
  *
- * Приоритет:
- *  1. Если validation-ошибка → склеиваем все сообщения из `meta.errors` (по всем полям)
- *  2. Иначе — `err.message` (generic от бэка)
- *  3. Иначе — `fallback`
+ * Priority:
+ *  1. If it's a validation error → join all messages from `meta.errors` (across all fields)
+ *  2. Otherwise — `err.message` (generic message from the backend)
+ *  3. Otherwise — `fallback`
  */
 declare function getCartErrorMessage(e: unknown, fallback: string): string;
 
 /**
- * Race-safe выполнение мутаций корзины.
+ * Race-safe execution of cart mutations.
  *
- * Проблема: SDK Zenky не поддерживает AbortSignal — нельзя физически отменить
- * запрос на полпути. Если пользователь быстро жмёт `+ → доставка → оплата`,
- * ответы могут прийти в произвольном порядке и устаревший ответ перепишет
- * свежее состояние (race condition).
+ * Problem: the Zenky SDK doesn't support AbortSignal — a request can't actually
+ * be canceled halfway through. If the user quickly clicks `+ → delivery →
+ * payment`, responses can arrive out of order and a stale response can
+ * overwrite fresher state (a race condition).
  *
- * Решение: версионирование per-kind. У каждого вида операции свой счётчик —
- * новый вызов инкрементирует его, после await callback проверяет «я ещё актуален?»
- * через `isStale()`. Если устарел — side-effect (`cartStore.setOrder`) пропускается.
- * HTTP-запрос всё равно завершается на бэке (минорный overhead), но фронт
- * игнорирует результат → race гарантированно не пройдёт.
+ * Solution: per-kind versioning. Each operation kind has its own counter — a
+ * new call increments it, and after the await the callback checks "am I still
+ * current?" via `isStale()`. If it's stale, the side effect
+ * (`cartStore.setOrder`) is skipped. The HTTP request still completes on the
+ * backend (a minor overhead), but the frontend ignores the result, so the race
+ * can never land.
  *
- * Дополнительно — debounce per-kind. Быстрые подряд клики «++++» схлопываются
- * в один запрос после паузы.
+ * Also includes per-kind debounce. Rapid clicks like "++++" collapse into a
+ * single request after a pause.
  *
- * Состояние версий общее для composables одного storefront runtime, но изолировано
- * между SSR-запросами и отдельными Vue-приложениями.
+ * Version state is shared across composables within one storefront runtime,
+ * but isolated between SSR requests and separate Vue apps.
  */
 /**
- * `cart-line-${lineKey}` — динамический ключ строки корзины: add и remove одной
- * строки делят kind, т.к. конфликтуют по одному ресурсу.
+ * `cart-line-${lineKey}` — dynamic cart line key: add and remove for the same
+ * line share a kind, since they contend for the same resource.
  */
 type MutationKind = 'delivery' | 'delivery-settle' | 'payment' | 'promocode' | 'bonuses' | 'customer' | 'total' | 'settings' | 'checkout' | `cart-line-${string}`;
 interface MutationOptions {
-    /** Уникальный kind — мутации одного kind заменяют друг друга */
+    /** Unique kind — mutations of the same kind replace each other */
     kind: MutationKind;
-    /** Debounce в мс перед отправкой (0 = без debounce) */
+    /** Debounce in ms before sending (0 = no debounce) */
     debounce?: number;
 }
 interface CartMutationComposable {
     /**
-     * Запустить мутацию. Внутри callback'а можно делать side-effect только
-     * если `isStale()` вернул `false` — иначе старый результат затрёт свежий.
+     * Run a mutation. Inside the callback, only do the side effect if
+     * `isStale()` returns `false` — otherwise a stale result would overwrite a
+     * fresher one.
      *
-     * Возвращает результат `fn` или `undefined` если был stale.
+     * Returns the result of `fn`, or `undefined` if it went stale.
      *
      * @example
      *   await run({ kind: 'payment', debounce: 300 }, async (isStale) => {
      *     const order = await sdk.orders.setOrderPayments(...)
-     *     if (isStale()) return  // Пришёл новый клик — наш результат устарел
+     *     if (isStale()) return  // A new click came in — our result is stale
      *     cartStore.setOrder(order)
      *     return order
      *   })
      */
     run: <T>(options: MutationOptions, fn: (isStale: () => boolean) => Promise<T>) => Promise<T | undefined>;
-    /** Получить текущую версию kind'а — для тестов / отладки */
+    /** Get the current version of a kind — for tests / debugging */
     getVersion: (kind: MutationKind) => number;
     /**
-     * Bump-нуть версии всех kind с указанным префиксом — все in-flight операции,
-     * матчащие префикс, станут stale и их side-effect'ы будут проигнорированы.
+     * Bump the versions of all kinds with the given prefix — every in-flight
+     * operation matching the prefix becomes stale and its side effects are
+     * ignored.
      *
-     * Используется при `clearAndResetCart` / `logout` — отменить все pending
-     * мутации старого заказа, чтобы поздние ответы не записались в свежий стейт.
+     * Used by `clearAndResetCart` / `logout` — to cancel all pending mutations
+     * of the old order, so late responses don't get written into the fresh
+     * state.
      */
     bumpKindsWithPrefix: (prefix: string) => void;
 }
@@ -208,31 +212,31 @@ interface CartQuantities {
 declare function useCartQuantities(): CartQuantities;
 
 interface CheckoutFlowFlags {
-    /** Режим из настроек магазина (Disabled / Preauth / Confirmation) */
     mode: ComputedRef<OrderAuthenticationMethod>;
-    /** Нужна авторизация перед submit (открывается AuthModal вместо checkoutOrder) */
+    /** Auth is required before submit (opens AuthModal instead of checkoutOrder) */
     needsAuth: ComputedRef<boolean>;
-    /** Нужно показать CustomerForm в корзине (phone + name) */
+    /** CustomerForm (phone + name) must be shown in the cart */
     needsCustomerForm: ComputedRef<boolean>;
 }
 /**
- * Определяет поведение чекаута в зависимости от настроек магазина.
+ * Determines checkout behavior based on store settings.
  *
- * Матрица:
+ * Matrix:
  *   ┌──────────────┬──────────┬──────────────────┐
  *   │ mode         │ needsAuth│ needsCustomerForm│
  *   ├──────────────┼──────────┼──────────────────┤
  *   │ Preauth      │ true     │ false            │
- *   │ Confirmation │ false    │ true  (гости)    │
- *   │ Disabled     │ false    │ true  (гости)    │
+ *   │ Confirmation │ false    │ true  (guests)   │
+ *   │ Disabled     │ false    │ true  (guests)   │
  *   └──────────────┴──────────┴──────────────────┘
  *
- * Нужна ли SMS-подтверждение — фронт не вычисляет: бэк возвращает
- * `confirmation.required` в ответе `checkoutOrder`, и UI реагирует на него.
+ * Whether SMS confirmation is needed is not computed on the frontend: the
+ * backend returns `confirmation.required` in the `checkoutOrder` response,
+ * and the UI reacts to that.
  *
- * Примечание: `needsCustomerForm` сейчас возвращает true для гостей во всех
- * режимах кроме Preauth. Для авторизованных клиентов форма не нужна
- * (данные автозаполняются через authStore).
+ * Note: `needsCustomerForm` currently returns true for guests in every mode
+ * except Preauth. Authenticated customers don't need the form (their data is
+ * autofilled from authStore).
  */
 declare function useCheckoutFlow(): CheckoutFlowFlags;
 
@@ -249,8 +253,9 @@ interface CartCredentials {
     isOrderActive: (order: Order) => boolean;
 }
 /**
- * Управление credentials заказа. Персистенс order-id/token — через порт `storage`
- * (ядро не знает про useCookie). Рефы инициализируются из storage, persist пишет в оба.
+ * Manages order credentials. Order id/token persistence goes through the `storage`
+ * port (the core doesn't know about useCookie). The refs are initialized from
+ * storage; persisting writes to both.
  */
 declare function useCartCredentials(): CartCredentials;
 
@@ -262,15 +267,15 @@ interface OrderTotal {
 declare function useOrderTotal(): OrderTotal;
 
 interface OrderSettingsComposable {
-    /** Полный снепшот настроек — читается из `cartStore.orderSettings` */
+    /** Full settings snapshot — read from `cartStore.orderSettings` */
     settings: ComputedRef<OrderSettings | null>;
     paymentMethods: ComputedRef<OrderPaymentMethod[]>;
     deliveryMethods: ComputedRef<OrderDeliveryMethod[]>;
     loading: Ref<boolean>;
     /**
-     * Перезапросить настройки с бэка. Вызывается:
-     * - при старте (через useCartInitialization)
-     * - после setOrderDeliveryMethod (набор payment-методов меняется от доставки)
+     * Refetches settings from the backend. Called:
+     * - on startup (via useCartInitialization)
+     * - after setOrderDeliveryMethod (the set of payment methods changes based on delivery)
      */
     fetchSettings: () => Promise<void>;
 }
@@ -282,30 +287,31 @@ interface OrderCredentialsLike {
 }
 interface RetryOptions {
     /**
-     * ID существующей online-payment транзакции (`order.payments[].id` где
-     * `is_online === true && status === 'pending'`). Используется как fallback
-     * если основной retry-эндпоинт вернул ошибку (typically 409
-     * `order_is_not_submitted` для свежих pending-заказов).
+     * ID of an existing online-payment transaction (`order.payments[].id`
+     * where `is_online === true && status === 'pending'`). Used as a fallback
+     * if the main retry endpoint returns an error (typically 409
+     * `order_is_not_submitted` for freshly created pending orders).
      */
     transactionId?: string | null;
     /**
-     * Куда вернуть юзера после оплаты. По дефолту `window.location.href` —
-     * на success-странице это правильно (вернёт обратно на success), но
-     * со страницы заказа `/me/orders/[id]` лучше передать success-URL явно,
-     * иначе после оплаты юзер останется на странице заказа без `?payment=`
-     * query и не увидит результат оплаты.
+     * Where to send the user back after payment. Defaults to
+     * `window.location.href` — correct on the success page (sends back to
+     * success), but from the order page `/me/orders/[id]` it's better to pass
+     * the success URL explicitly, otherwise after payment the user is left on
+     * the order page without the `?payment=` query and never sees the
+     * payment result.
      */
     currentUrl?: string;
 }
 /**
- * Повторная попытка онлайн-оплаты заказа.
+ * Retries an order's online payment.
  *
- * **Стратегия (двухуровневая)**:
- * 1. `sdk.orders.retryOnlinePayment` — официальный retry-эндпоинт (submitted-заказы).
- * 2. `getOnlinePaymentRedirect(transactionId)` — fallback для pending-заказов (409
+ * **Strategy (two-tier)**:
+ * 1. `sdk.orders.retryOnlinePayment` — the official retry endpoint (submitted orders).
+ * 2. `getOnlinePaymentRedirect(transactionId)` — fallback for pending orders (409
  *    `order_is_not_submitted`).
  *
- * Возвращает `redirect_url` или `null` если оба способа упали.
+ * Returns `redirect_url`, or `null` if both approaches fail.
  */
 declare function useOnlinePaymentRetry(): {
     retry(creds: OrderCredentialsLike, options?: RetryOptions): Promise<string | null>;
@@ -349,7 +355,7 @@ interface BonusesReconciliationDeps {
     notifier: Notifier;
     activity?: ActivityReporter;
 }
-/** Headless-синхронизация применённых бонусов после order-change (от server-state + intent). */
+/** Headless sync of applied bonuses after an order change (using server state + intent). */
 declare function useBonusesReconciliation(deps: BonusesReconciliationDeps): BonusesReconciliation;
 
 interface CartRecalculation {
@@ -360,14 +366,16 @@ interface CartRecalculationDeps {
     activity?: ActivityReporter;
 }
 /**
- * Orchestration после order-change: total → синхронизация бонусов → промо/min-price.
- * Вызывать явно после мутаций заказа; не привязывать к каждому fetchTotal (цикл).
+ * Orchestration after an order change: total → bonus sync → promo/min-price.
+ * Call this explicitly after order mutations; don't wire it to every fetchTotal
+ * call (that would create a cycle).
  */
 declare function useCartRecalculation(deps: CartRecalculationDeps): CartRecalculation;
 
 /**
- * View прикреплённого покупателя для UI. `national` форматируется потребителем
- * (нужна app-специфичная маска страны — Nuxt useAppConfig), ядро его не считает.
+ * View of the attached customer, for the UI. `national` is formatted by the
+ * consumer (it needs an app-specific country mask — Nuxt useAppConfig); the
+ * core does not compute it.
  */
 interface CachedCustomerView {
     first_name: string;
@@ -379,9 +387,9 @@ interface CachedCustomerView {
     };
 }
 /**
- * Контракт client-local кэша покупателя. Реализация — на стороне потребителя
- * (localStorage + app-форматтер телефона), инжектится параметром в
- * `useCustomerAttach` / `useCartCustomerAttachment`.
+ * Contract for the client-local customer cache. Implemented by the consumer
+ * (localStorage + an app-specific phone formatter), injected as a parameter
+ * into `useCustomerAttach` / `useCartCustomerAttachment`.
  */
 interface AttachedCustomerCache {
     forOrder: (orderId: MaybeRefOrGetter<string | null | undefined>) => ComputedRef<CachedCustomerView | null>;
@@ -390,50 +398,51 @@ interface AttachedCustomerCache {
 }
 
 interface CustomerAttachComposable {
-    /** Прикреплён ли покупатель к заказу (есть `order.customer`) */
+    /** Whether the customer is attached to the order (there's `order.customer`) */
     isAttached: ComputedRef<boolean>;
     /**
-     * Привязать customer к заказу (phone + имя + опционально фамилия / дата рождения).
-     * После успешного вызова заказ перечитываем с includes — чтобы `order.customer`
-     * попал в `cartStore.order` и компоненты могли его увидеть.
+     * Attach a customer to the order (phone + name + optional last name / birth date).
+     * After a successful call, the order is re-fetched with includes — so that
+     * `order.customer` lands in `cartStore.order` and components can see it.
      *
-     * Обёрнуто в activity('custom') — блокирует кнопку «Оформить» на время запроса.
+     * Wrapped in activity('custom') — blocks the "Checkout" button while the
+     * request is in flight.
      */
     attach: (request: SetOrderCustomerRequest) => Promise<void>;
 }
 /**
- * Работа с прикреплением клиента к заказу.
+ * Handles attaching a customer to the order.
  *
- * Используется в двух режимах OrderAuthenticationMethod:
- * - `Disabled` — гость заполняет phone+name, `attach` до `checkoutOrder`
- * - `Confirmation` — гость заполняет phone+name, после `checkoutOrder` придёт SMS
+ * Used in two OrderAuthenticationMethod modes:
+ * - `Disabled` — the guest fills in phone+name, `attach` runs before `checkoutOrder`
+ * - `Confirmation` — the guest fills in phone+name, an SMS arrives after `checkoutOrder`
  *
- * Для `Preauth` обычно не нужно — customer прикрепляется автоматически,
- * когда SDK имеет `api_token` клиента (см. `authStore`).
+ * Usually not needed for `Preauth` — the customer is attached automatically
+ * once the SDK has the client's `api_token` (see `authStore`).
  *
- * @param cache client-local кэш покупателя (реализация потребителя — localStorage).
+ * @param cache client-local customer cache (implemented by the consumer — localStorage).
  */
 declare function useCustomerAttach(cache: AttachedCustomerCache): CustomerAttachComposable;
 
 /**
- * Привязывает customer'а авторизованного юзера к текущему заказу.
+ * Attaches the authenticated user's customer record to the current order.
  *
- * Срабатывает в двух кейсах:
- * 1) Юзер залогинился (auth state изменилась) — `notifyOnPhoneChange = true`,
- *    в этом сценарии возможно был анонимный customer с другим телефоном —
- *    показываем тост, если телефон реально изменился.
- * 2) У авторизованного юзера появился новый заказ без customer'а
- *    (например, после очистки корзины и добавления товара) — `notifyOnPhoneChange = false`,
- *    тост не нужен, это безшумная синхронизация.
+ * Runs in two cases:
+ * 1) The user logged in (auth state changed) — `notifyOnPhoneChange = true`;
+ *    there may have been an anonymous customer with a different phone, so we
+ *    show a toast if the phone actually changed.
+ * 2) An authenticated user got a new order with no customer attached
+ *    (e.g. after clearing the cart and adding a product) — `notifyOnPhoneChange = false`,
+ *    no toast needed, this is a silent sync.
  *
- * @param cache client-local кэш покупателя (реализация потребителя — localStorage).
+ * @param cache client-local customer cache (implemented by the consumer — localStorage).
  */
 declare function useCartCustomerAttachment(cache: AttachedCustomerCache): void;
 
 interface CartStockWatcher {
     /**
-     * Реагирует на смену склада в обновлённом заказе: переключает stock,
-     * перегружает каталог при смене хэша и валидирует товары корзины.
+     * Reacts to a stock change in the updated order: switches the stock,
+     * reloads the catalog if the hash changed, and validates the cart items.
      */
     handleStockChange: (updatedOrder: Order) => Promise<void>;
 }
@@ -459,17 +468,16 @@ interface OrderDelivery {
 declare function useOrderDelivery(deps?: OrderDeliveryDeps): OrderDelivery;
 
 interface OrderPromocodeComposable {
-    /** Применённый к заказу промокод (читается из cartStore.order.promocode) */
+    /** Promocode applied to the order (read from cartStore.order.promocode) */
     applied: ComputedRef<OrderPromocode | null>;
     isApplied: ComputedRef<boolean>;
     loading: Ref<boolean>;
-    /** Сообщение об ошибке (невалидный / просрочен / не подходит к заказу) */
+    /** Error message (invalid / expired / doesn't apply to this order) */
     errorMessage: Ref<string | null>;
-    /** Применить промокод. Обёрнуто в activity('promocode'). */
+    /** Applies the promocode. Wrapped in activity('promocode'). */
     apply: (code: string) => Promise<void>;
-    /** Убрать ранее применённый промокод */
     remove: () => Promise<void>;
-    /** Сбросить состояние ошибки (например, при редактировании поля) */
+    /** Resets the error state (e.g. when the field is being edited) */
     clearError: () => void;
 }
 interface OrderPromocodeDeps {
@@ -489,6 +497,7 @@ interface CartItemRequest {
     variantLabel?: string;
     promotionId?: string;
     promotionRewardId?: string;
+    recommendationsBlock?: RecommendationsBlock;
 }
 interface CartDependencies {
     notifier: Notifier;
@@ -504,32 +513,29 @@ interface CartOperations {
 }
 declare function useCartOperations(credentials: CartCredentials, initialization: CartInitialization, sdk: ZenkyStorefront, deps: CartDependencies): CartOperations;
 
-/** Провайдер reCAPTCHA-payload (реализация потребителя — Google reCAPTCHA v3). */
+/** reCAPTCHA payload provider (implemented by the consumer app — Google reCAPTCHA v3). */
 type RecaptchaPayloadProvider = (action: RecaptchaAction) => Promise<{
     token: string;
 } | undefined>;
 interface CheckoutSubmitComposable {
-    /** Последний результат `checkoutOrder` — нужен для UI (ConfirmationModal / online redirect) */
+    /** Last `checkoutOrder` result — needed by the UI (ConfirmationModal / online redirect) */
     result: Ref<OrderCheckoutResult | null>;
-    /** Идёт ли сейчас submit */
     submitting: Ref<boolean>;
     /**
-     * Отправить заказ.
-     * Собирает `OrderCheckoutRequest` из `cartStore` (notes + persons_count).
-     * Возвращает `OrderCheckoutResult` с флагами confirmation/online_payment.
+     * Collects `OrderCheckoutRequest` from `cartStore` (notes + persons_count).
+     * Returns `OrderCheckoutResult` with confirmation/online_payment flags.
      */
     submit: () => Promise<OrderCheckoutResult | null>;
-    /** Подтвердить SMS-код (после checkoutOrder с confirmation.required) */
+    /** Confirm the SMS code (after checkoutOrder returned confirmation.required) */
     confirm: (code: string) => Promise<boolean>;
-    /** Переотправить код (с backoff — должен следить UI) */
+    /** Resend the code (with backoff — the UI is responsible for that) */
     resendCode: () => Promise<boolean>;
-    /** Отменить pending-заказ (cancelOrder) */
     cancel: () => Promise<boolean>;
 }
 /**
- * Финальный submit заказа + SMS-подтверждение.
+ * Final order submit + SMS confirmation.
  *
- * @param getRecaptchaPayload провайдер reCAPTCHA-токена (app-специфичен, инжектится).
+ * @param getRecaptchaPayload reCAPTCHA token provider (app-specific, injected).
  */
 declare function useCheckoutSubmit(getRecaptchaPayload: RecaptchaPayloadProvider): CheckoutSubmitComposable;
 
@@ -556,7 +562,7 @@ interface StorefrontCart {
 }
 declare function useStorefrontCart(): StorefrontCart;
 
-/** Данные товара для показа в модалке гейта (как строка корзины). */
+/** Product data for display in the gate modal (shaped like a cart line). */
 interface RestrictionGateProduct {
     name: string;
     image: Media | null;
@@ -579,9 +585,10 @@ interface RestrictedAddToCart {
 declare function useRestrictedAddToCart(): RestrictedAddToCart;
 
 /**
- * Позиции корзины, видимые покупателю: серверное количество с учётом оптимистичной дельты.
- * Единый источник для списка, футера и подсветки — иначе блокировка чекаута, поиск
- * блокирующей позиции и реальный рендер списка могут разъехаться.
+ * Cart lines visible to the customer: server quantity adjusted by the optimistic
+ * delta. A single source for the list, footer, and highlighting — otherwise
+ * checkout blocking, finding the blocking line, and the actual rendered list
+ * could drift apart.
  */
 declare function useVisibleCartVariants(): ComputedRef<OrderProductVariant[]>;