orionplace-react 0.1.0 → 0.2.0

package/templates/lib/orionplace/cartLabels.ts

@@ -0,0 +1,261 @@
+const en = {
+  title: 'Cart',
+  checkout: 'Checkout',
+  checkoutAction: 'Checkout',
+  items: 'Items',
+  empty: 'Your cart is empty.',
+  browse: 'Continue shopping',
+  address: 'Delivery address',
+  addAddress: 'Add',
+  chooseAddress: 'Choose a saved address',
+  selectedAddress: 'Delivery to',
+  unsavedAddress:
+    'This address is not in your saved addresses. Choose a saved address to replace it.',
+  abroadHidden:
+    'Saved addresses in countries without delivery are not listed.',
+  savedAbroad:
+    'The address is saved, but there is no delivery to this country. Choose another address.',
+  payment: 'Payment method',
+  choosePayment: 'Choose payment method',
+  recipient: 'Recipient',
+  myself: 'Myself',
+  myselfHint: 'Myself: I will receive the order',
+  otherRecipient: 'Other',
+  otherRecipientHint: 'Other recipient',
+  name: 'Full name',
+  phone: 'Phone number',
+  comment: 'Order comment',
+  quantity: 'Quantity',
+  delivery: 'Delivery',
+  chooseDelivery: 'Choose delivery',
+  selectDelivery: 'Please select a delivery method',
+  shipment: 'Shipment',
+  of: 'of',
+  shipsFrom: 'Ships from',
+  digitalDelivery: 'Digital delivery',
+  digitalItems: 'Digital items, no shipping needed',
+  splitShipments:
+    'Your order ships in {count} parts from different stores. Choose delivery for each part.',
+  choose: 'Choose',
+  refreshDelivery: 'Refresh',
+  refreshDeliveryHint: 'Refresh delivery methods',
+  noDelivery: 'No delivery methods are available. Try another address.',
+  deliveryChanged:
+    'Delivery conditions changed. Check the selected method and price.',
+  pickup: 'Choose a pickup point',
+  pickupAction: 'Choose',
+  noPoints: 'No pickup points were returned.',
+  pointSearch: 'Find a pickup point by address',
+  courier: 'Confirm delivery to the selected address',
+  courierAction: 'Confirm',
+  pickupType: 'Pickup point',
+  courierType: 'Courier delivery',
+  selectedPoint: 'Selected',
+  postalCode: 'Postal code',
+  pickupMap: 'Pickup points on the map',
+  mapUnavailable: 'The map could not be loaded.',
+  remove: 'Remove',
+  clear: 'Clear',
+  clearQuestion: 'Remove all items from your cart?',
+  unavailable: 'Unavailable for this order',
+  estimate: 'Estimated delivery cost',
+  goods: 'Items',
+  discount: 'Discount',
+  promoDiscount: 'Promo discount',
+  deliveryDiscount: 'Delivery discount',
+  total: 'Total',
+  promo: 'Promo code',
+  apply: 'Apply',
+  removePromo: 'Remove',
+  removePromoHint: 'Remove promo code',
+  promoSignIn: 'Sign in to apply a promo code',
+  promoRemoved: 'Promo code {code} was removed from the cart.',
+  promoNotApplied: 'Promo code {code} was not applied.',
+  promoMinimumOrder: 'Minimum order for this code: {amount}.',
+  promoMissingAmount: 'Add {amount} more of the covered products.',
+  // Why a promo code gives no discount, by `promo_notice.reason`. OrionMarketplace's
+  // own `message` is shown for a reason this list does not name.
+  promoReasons: {
+    no_lines: 'Add items to the cart to use this promo code.',
+    not_matched: 'The promo code does not cover the items in your cart.',
+    product_discounted:
+      'The promo code does not apply to items that already have a discount.',
+    below_minimum: 'The order total is below the promo code minimum.',
+    subscriptions_only: 'This promo code is for subscriptions only.',
+    too_small: 'The cart total is too small for this promo code.',
+    nothing_to_ship:
+      'Delivery is already free, so the promo code gives nothing.',
+    expired: 'The promo code has expired.',
+    not_active: 'The promo code is no longer active.',
+    not_started: 'The promotion has not started yet.',
+    usage_limit: 'The promo code has been used the maximum number of times.',
+    promotion_limit: 'The promotion has run out.',
+    not_yours: 'This promo code belongs to another customer.',
+    personal_limit:
+      'You have already used this promo code the maximum number of times.',
+    first_order_only: 'This promo code is for the first purchase only.',
+    wrong_domain: 'This promo code is not valid in this store.',
+  } as Record<string, string>,
+  options: 'Item options',
+  optionLimit: 'Maximum quantity: {count}',
+  optionUnavailable: 'This option cannot be added now.',
+  optionSelected: 'Also selected',
+  optionSingle: 'One choice',
+  optionRequired: 'Required',
+  optionMissing: 'Needed to place the order',
+  optionMultiple: 'Several choices',
+  optionFile: 'Attach a file',
+  optionText: 'Your text',
+  selectedFile: 'Attached file',
+  optionFileLimit: 'Up to {size} MB',
+  optionFileTooLarge: 'The file is larger than {size} MB.',
+  clearOption: 'Clear',
+  clearOptionHint: 'Clear saved text and file',
+  stockChanged: 'Item quantities or prices changed. Please review your cart.',
+  placeOrder: 'Order',
+  created: 'Order created',
+  viewOrder: 'View order',
+  paymentLinkFailed:
+    'The order is placed, but the payment link could not be created: {error}. Pay for the order later on its page.',
+  payLater: 'Open the order to pay',
+  review: 'Review your items, delivery and total before placing the order.',
+  refreshRequired: 'Refresh your cart before continuing.',
+  orderUncertain:
+    'Could not confirm the order. Check your order history before trying again.',
+};
+
+const ru: typeof en = {
+  title: 'Корзина',
+  checkout: 'Оформление заказа',
+  checkoutAction: 'Оформить',
+  items: 'Товары',
+  empty: 'Корзина пуста.',
+  browse: 'Продолжить покупки',
+  address: 'Адрес доставки',
+  addAddress: 'Добавить',
+  chooseAddress: 'Выберите сохранённый адрес',
+  selectedAddress: 'Доставка по адресу',
+  unsavedAddress:
+    'Этого адреса нет среди сохранённых. Чтобы заменить его, выберите сохранённый адрес.',
+  abroadHidden:
+    'Сохранённые адреса в странах без доставки не показаны.',
+  savedAbroad:
+    'Адрес сохранён, но доставки в эту страну нет. Выберите другой адрес.',
+  payment: 'Способ оплаты',
+  choosePayment: 'Выберите способ оплаты',
+  recipient: 'Получатель',
+  myself: 'Себе',
+  myselfHint: 'Себе: получу заказ самостоятельно',
+  otherRecipient: 'Другому',
+  otherRecipientHint: 'Другому получателю',
+  name: 'ФИО',
+  phone: 'Номер телефона',
+  comment: 'Комментарий к заказу',
+  quantity: 'Количество',
+  delivery: 'Доставка',
+  chooseDelivery: 'Выбрать доставку',
+  selectDelivery: 'Выберите способ доставки',
+  shipment: 'Отправление',
+  of: 'из',
+  shipsFrom: 'Отправка из',
+  digitalDelivery: 'Электронная доставка',
+  digitalItems: 'Цифровые товары, доставка не нужна',
+  splitShipments:
+    'Заказ придёт несколькими отправлениями из разных магазинов: {count}. Выберите доставку для каждого.',
+  choose: 'Выбрать',
+  refreshDelivery: 'Обновить',
+  refreshDeliveryHint: 'Обновить способы доставки',
+  noDelivery: 'Нет доступных способов доставки. Попробуйте другой адрес.',
+  deliveryChanged:
+    'Условия доставки изменились. Проверьте выбранный способ и стоимость.',
+  pickup: 'Выбрать пункт выдачи',
+  pickupAction: 'Выбрать',
+  noPoints: 'Пункты выдачи не найдены.',
+  pointSearch: 'Найти пункт выдачи по адресу',
+  courier: 'Подтвердить доставку по выбранному адресу',
+  courierAction: 'Подтвердить',
+  pickupType: 'Пункт выдачи',
+  courierType: 'Курьерская доставка',
+  selectedPoint: 'Выбран',
+  postalCode: 'Индекс',
+  pickupMap: 'Пункты выдачи на карте',
+  mapUnavailable: 'Не удалось загрузить карту.',
+  remove: 'Удалить',
+  clear: 'Очистить',
+  clearQuestion: 'Удалить все товары из корзины?',
+  unavailable: 'Недоступны для этого заказа',
+  estimate: 'Предварительная стоимость доставки',
+  goods: 'Товары',
+  discount: 'Скидка',
+  promoDiscount: 'Скидка промокода',
+  deliveryDiscount: 'Скидка на доставку',
+  total: 'Итого',
+  promo: 'Промокод',
+  apply: 'Применить',
+  removePromo: 'Удалить',
+  removePromoHint: 'Удалить промокод',
+  promoSignIn: 'Войдите, чтобы применить промокод',
+  promoRemoved: 'Промокод {code} удалён из корзины.',
+  promoNotApplied: 'Промокод {code} не применён.',
+  promoMinimumOrder: 'Минимальная сумма заказа для промокода: {amount}.',
+  promoMissingAmount: 'Добавьте товаров ещё на {amount}.',
+  promoReasons: {
+    no_lines: 'Добавьте товары в корзину, чтобы применить промокод.',
+    not_matched: 'Промокод не действует на товары в корзине.',
+    product_discounted:
+      'Промокод не действует на товары, у которых уже есть скидка.',
+    below_minimum: 'Сумма заказа меньше минимальной для промокода.',
+    subscriptions_only: 'Этот промокод действует только на подписки.',
+    too_small: 'Сумма корзины слишком мала для этого промокода.',
+    nothing_to_ship:
+      'Доставка уже бесплатная, промокод ничего не даёт.',
+    expired: 'Срок действия промокода истёк.',
+    not_active: 'Промокод больше не действует.',
+    not_started: 'Акция ещё не началась.',
+    usage_limit: 'Промокод уже использован максимальное число раз.',
+    promotion_limit: 'Акция закончилась.',
+    not_yours: 'Этот промокод выдан другому покупателю.',
+    personal_limit:
+      'Вы уже использовали этот промокод максимальное число раз.',
+    first_order_only: 'Промокод действует только на первую покупку.',
+    wrong_domain: 'Промокод не действует в этом магазине.',
+  },
+  options: 'Дополнения к товару',
+  optionLimit: 'Максимальное количество: {count}',
+  optionUnavailable: 'Это дополнение сейчас нельзя добавить.',
+  optionSelected: 'Также выбрано',
+  optionSingle: 'Один вариант',
+  optionRequired: 'Обязательно',
+  optionMissing: 'Нужно для оформления заказа',
+  optionMultiple: 'Несколько вариантов',
+  optionFile: 'Прикрепить файл',
+  optionText: 'Ваш текст',
+  selectedFile: 'Прикреплённый файл',
+  optionFileLimit: 'До {size} МБ',
+  optionFileTooLarge: 'Файл больше {size} МБ.',
+  clearOption: 'Очистить',
+  clearOptionHint: 'Очистить сохранённый текст и файл',
+  stockChanged: 'Количество или цены товаров изменились. Проверьте корзину.',
+  placeOrder: 'Заказать',
+  created: 'Заказ создан',
+  viewOrder: 'Посмотреть заказ',
+  paymentLinkFailed:
+    'Заказ создан, но ссылку на оплату получить не удалось: {error}. Оплатите заказ позже на странице заказа.',
+  payLater: 'Открыть заказ для оплаты',
+  review: 'Проверьте товары, доставку и итоговую сумму перед оформлением.',
+  refreshRequired: 'Обновите корзину, чтобы продолжить.',
+  orderUncertain:
+    'Не удалось подтвердить создание заказа. Перед повторной попыткой проверьте историю заказов.',
+};
+
+/**
+ * The notice of an order placed without a payment link: the backend's reason
+ * is shown as it came, without its closing full stop.
+ */
+export function cartPaymentLinkError(template: string, error: string) {
+  return template.replace('{error}', error.trim().replace(/[.\s]+$/, ''));
+}
+
+export function cartLabels(locale: string) {
+  return locale.toLowerCase().startsWith('ru') ? ru : en;
+}

package/templates/lib/orionplace/cartOptions.ts

@@ -0,0 +1,115 @@
+import type { IProduct } from '@/interfaces/orionplace/products/IProduct';
+import type {
+  ICartDelivery,
+  ICartOption,
+  ICartOptionGroup,
+} from '@/interfaces/orionplace/cart/ICartData';
+
+export interface ICartOptionRow {
+  option: ICartOption;
+  product: IProduct;
+  maxQuantity: number;
+}
+
+export interface ICartOptionCard {
+  key: string;
+  rows: ICartOptionRow[];
+  productIds: number[];
+}
+
+const NO_LIMIT = 0;
+
+function quantityInOtherRows(group: ICartOptionGroup, option: ICartOption) {
+  return (group.options ?? [])
+    .filter(
+      (row) => row.id !== option.id && row.product?.id === option.product?.id,
+    )
+    .reduce((total, row) => total + row.quantity, 0);
+}
+
+export function cartOptionMaxQuantity(
+  group: ICartOptionGroup,
+  option: ICartOption,
+) {
+  const limits = [option.quantity + (option.quantity_left ?? 0)];
+  const perRow = group.limits?.c_max_product_quantity_in_group ?? NO_LIMIT;
+  const perProduct =
+    group.limits?.c_max_products_quantity_for_group ?? NO_LIMIT;
+
+  if (perRow > NO_LIMIT) {
+    limits.push(perRow);
+  }
+  if (perProduct > NO_LIMIT) {
+    limits.push(perProduct - quantityInOtherRows(group, option));
+  }
+
+  return Math.max(0, Math.floor(Math.min(...limits)));
+}
+
+export function cartOptionRows(group: ICartOptionGroup): ICartOptionRow[] {
+  const rows: ICartOptionRow[] = [];
+  for (const option of group.options ?? []) {
+    if (option.product) {
+      rows.push({
+        option,
+        product: option.product,
+        maxQuantity: cartOptionMaxQuantity(group, option),
+      });
+    }
+  }
+  return rows;
+}
+
+export function cartOptionProducts(group: ICartOptionGroup) {
+  return cartOptionRows(group).map((row) => row.product);
+}
+
+export function cartOptionCards(group: ICartOptionGroup): ICartOptionCard[] {
+  const cards = new Map<string, ICartOptionCard>();
+  for (const row of cartOptionRows(group)) {
+    const productGroup = row.product.product_group_id;
+    const key =
+      Number.isInteger(productGroup) && Number(productGroup) > 0
+        ? `group:${productGroup}`
+        : `product:${row.product.id}`;
+    const card = cards.get(key) ?? { key, rows: [], productIds: [] };
+    card.rows.push(row);
+    card.productIds.push(row.product.id);
+    cards.set(key, card);
+  }
+  return [...cards.values()];
+}
+
+export function cartOptionActiveRow(card: ICartOptionCard, chosen?: number) {
+  return (
+    card.rows.find((row) => row.option.id === chosen) ??
+    card.rows.find((row) => row.option.quantity > 0) ??
+    card.rows[0]
+  );
+}
+
+export function cartOptionGroupFilled(group: ICartOptionGroup) {
+  const type = group.option_type?.option_type || '';
+  if (type === 'text' || type === 'textarea') {
+    return group.option_text_data.trim() !== '';
+  }
+  if (type === 'file') {
+    return Boolean(group.option_file_data);
+  }
+  return (group.options ?? []).some((option) => option.quantity > 0);
+}
+
+/**
+ * True when every required option group of every line in the shipments is
+ * filled. The backend refuses the order otherwise, so the place-order button
+ * waits for it like it waits for the delivery and the payment.
+ */
+export function cartRequiredOptionsFilled(deliveries: ICartDelivery[]) {
+  return deliveries.every((delivery) =>
+    (delivery.product_items ?? []).every((product) =>
+      (product?.option_group ?? []).every(
+        (group) => !group.option_group_required || cartOptionGroupFilled(group),
+      ),
+    ),
+  );
+}

package/templates/lib/orionplace/cartPreview.ts

@@ -0,0 +1,120 @@
+import type { ICartItemMutationResponse } from '@/interfaces/orionplace/cart/ICartActions';
+import type { ICartPreviewState } from '@/interfaces/orionplace/cart/ICartModal';
+import type { IProduct } from '@/interfaces/orionplace/products/IProduct';
+import { getAvailableNestedValueFromObject } from '@/lib/orionplace/presentation';
+
+export function cartPreviewLabels(locale: string) {
+  if (locale.toLowerCase().startsWith('ru')) {
+    return {
+      title: 'Корзина',
+      quantity: 'Товаров',
+      pieces: (count: number) => `${count} шт.`,
+      empty: 'В корзине пока нет товаров',
+      loading: 'Загрузка корзины…',
+      failed: 'Не удалось загрузить корзину. Повторите запрос.',
+      unavailable: 'Просмотр корзины недоступен.',
+      retry: 'Повторить',
+      remove: 'Удалить из корзины',
+      removeFailed: 'Не удалось удалить товар. Повторите попытку.',
+      checkout: 'Перейти в корзину',
+    };
+  }
+  return {
+    title: 'Cart',
+    quantity: 'Items',
+    pieces: (count: number) => `Qty ${count}`,
+    empty: 'Your cart is empty',
+    loading: 'Loading cart…',
+    failed: 'Could not load the cart. Please try again.',
+    unavailable: 'Cart preview is unavailable.',
+    retry: 'Retry',
+    remove: 'Remove from cart',
+    removeFailed: 'Could not remove the item. Please try again.',
+    checkout: 'Go to cart',
+  };
+}
+
+export function cartPreviewState(): ICartPreviewState {
+  return {
+    open: false,
+    pending: false,
+    products: [],
+    error: '',
+    removing: [],
+    removeError: '',
+  };
+}
+
+/** The preview response also carries the header's cart position counter. */
+export function cartPreviewCounter(
+  data: { cart?: { c_cart_positions?: unknown } } | null | undefined,
+): number | undefined {
+  const count = data?.cart?.c_cart_positions;
+
+  return Number.isInteger(count) ? (count as number) : undefined;
+}
+
+/** A removal is confirmed only by the new counter in its response. */
+export function cartPreviewRemoval(
+  data: ICartItemMutationResponse['page_data'] | undefined,
+): NonNullable<ICartItemMutationResponse['page_data']> {
+  if (!data || !Number.isInteger(data.c_cart_positions)) {
+    throw new Error('Invalid cart removal response');
+  }
+
+  return data;
+}
+
+/** The preview lists cart products only from a complete `cart_data` array. */
+export function cartPreviewProducts(
+  data: { cart_data?: unknown } | null | undefined,
+): IProduct[] {
+  const products = data?.cart_data;
+  const complete =
+    Array.isArray(products) &&
+    products.every(
+      (item) => item && typeof item.id === 'number' && item.locale,
+    );
+
+  if (!complete) {
+    throw new Error('Invalid cart preview response');
+  }
+
+  return products as IProduct[];
+}
+
+export function cartPreviewItems(
+  products: readonly IProduct[],
+  locale: string,
+  currencyId: string,
+) {
+  return products.map((product) => {
+    const counts = product.cart_counts;
+    const original =
+      counts?.cart_item_price_no_discount?.[currencyId]?.transform_value;
+    const final =
+      counts?.cart_item_price_after_promo?.[currencyId]?.transform_value;
+    return {
+      id: product.id,
+      cartItem: counts?.cart_id ?? 0,
+      name:
+        getAvailableNestedValueFromObject(
+          product.locale,
+          locale,
+          'product_name',
+        ) || `#${product.id}`,
+      image: product.images?.small?.[0],
+      quantity: counts?.modal_quantity ?? 0,
+      original: original ?? undefined,
+      price: final ?? original ?? undefined,
+      discounted:
+        original !== undefined && final !== undefined && final < original,
+    };
+  });
+}
+
+export function cartPreviewQuantity(
+  items: ReadonlyArray<{ quantity: number }>,
+) {
+  return items.reduce((total, item) => total + item.quantity, 0);
+}

package/templates/lib/orionplace/cartPromo.ts

@@ -0,0 +1,150 @@
+import { ECartPromoNoticeReason } from '@/interfaces/orionplace/cart/ICartData';
+import type { ICartPromoNotice } from '@/interfaces/orionplace/cart/ICartData';
+import type { IAppLoadCommonCurrency } from '@/interfaces/orionplace/appBase/appLoadCommon/IAppLoadCommonCurrency';
+import { formatDollarAmount } from '@/lib/orionplace/currency';
+import { fieldErrorText } from '@/lib/orionplace/api';
+
+interface IPromoNoticeLabels {
+  promoRemoved: string;
+  promoNotApplied: string;
+  promoMinimumOrder: string;
+  promoMissingAmount: string;
+  promoReasons: Record<string, string>;
+}
+
+/** A refused `marketing_promo_promo_apply`: OrionMarketplace's text and its notice. */
+export interface ICartPromoRefusal {
+  message: string;
+  notice: ICartPromoNotice | null;
+}
+
+/** What the cart writes for a promo notice: one sentence each. */
+export interface ICartPromoNoticeText {
+  title: string;
+  reason: string;
+  minimum: string;
+  missing: string;
+  text: string;
+}
+
+// Reasons about the cart's items. A code with one of them and
+// `is_removed: true` was refused when applied, so it was never in the cart.
+const CART_REASONS = new Set<string>([
+  ECartPromoNoticeReason.NO_LINES,
+  ECartPromoNoticeReason.NOT_MATCHED,
+  ECartPromoNoticeReason.PRODUCT_DISCOUNTED,
+  ECartPromoNoticeReason.BELOW_MINIMUM,
+  ECartPromoNoticeReason.SUBSCRIPTIONS_ONLY,
+  ECartPromoNoticeReason.TOO_SMALL,
+  ECartPromoNoticeReason.NOTHING_TO_SHIP,
+]);
+
+/**
+ * The cart's promo notice in the customer's words: the package's own text
+ * for a known `reason` (OrionMarketplace's `message` otherwise), the code it is about
+ * when the cart removed or refused it, and for `below_minimum` the minimum
+ * order and the amount still missing. Both are dollar amounts: with
+ * `currencies` they read «$ 544 ≈ 40 256 ₽» while another currency is
+ * selected. A notice limited to other currencies (`currency_ids`) is not
+ * shown.
+ */
+export function cartPromoNotice(
+  notice: ICartPromoNotice | null | undefined,
+  labels: IPromoNoticeLabels,
+  currencyId: string,
+  currency: IAppLoadCommonCurrency | undefined,
+  locale: string,
+  currencies?: Record<string, IAppLoadCommonCurrency> | null,
+): ICartPromoNoticeText | undefined {
+  if (!notice?.reason || !cartPromoNoticeShown(notice, currencyId)) {
+    return undefined;
+  }
+
+  const reason  = labels.promoReasons[notice.reason] || notice.message || '';
+  const heading = CART_REASONS.has(notice.reason)
+    ? labels.promoNotApplied
+    : labels.promoRemoved;
+  const title   = !notice.is_removed
+    ? ''
+    : notice.promocode
+      ? heading.replace('{code}', notice.promocode)
+      : heading.replace(' {code}', '');
+  const amount  = formatDollarAmount(
+    notice.minimum_order_amount,
+    currencyId,
+    currency,
+    locale,
+    currencies,
+  );
+  const minimum = amount
+    ? labels.promoMinimumOrder.replace('{amount}', amount)
+    : '';
+  const short   = hasAmount(notice.missing_amount)
+    ? formatDollarAmount(
+        notice.missing_amount,
+        currencyId,
+        currency,
+        locale,
+        currencies,
+      )
+    : '';
+  const missing = short
+    ? labels.promoMissingAmount.replace('{amount}', short)
+    : '';
+
+  return {
+    title,
+    reason,
+    minimum,
+    missing,
+    text: [title, reason, minimum, missing].filter(Boolean).join(' '),
+  };
+}
+
+/**
+ * `currency_ids` limits a notice to some currencies, for example a fixed
+ * code that takes $10 off in dollars and nothing in rubles; `null` or an
+ * absent list means every currency.
+ */
+export function cartPromoNoticeShown(
+  notice: Pick<ICartPromoNotice, 'currency_ids'>,
+  currencyId: string,
+): boolean {
+  const ids = notice.currency_ids;
+
+  return !Array.isArray(ids) || ids.map(String).includes(String(currencyId));
+}
+
+// OrionMarketplace sends zero in every currency once the minimum is reached.
+function hasAmount(amounts: ICartPromoNotice['missing_amount']): boolean {
+  return Object.values(amounts ?? {}).some(
+    (amount) => Number(amount?.transform_value) > 0,
+  );
+}
+
+/**
+ * OrionMarketplace refuses a promo code with a field error: the code is unknown or no
+ * longer valid (`form_errors.promocode`), or it gives this cart nothing
+ * (`form_errors.__all__` with `page_data.promo_notice`). Anything else, such
+ * as a lost connection, is not a refusal.
+ */
+export function cartPromoRefusal(error: unknown): ICartPromoRefusal | undefined {
+  if (!error || typeof error !== 'object' || !('fields' in error)) {
+    return undefined;
+  }
+
+  const fields  = error.fields;
+  const message = fields && typeof fields === 'object'
+    ? fieldErrorText(fields as Record<string, unknown>)
+    : '';
+  if (!message) {
+    return undefined;
+  }
+
+  const data    = 'data' in error ? error.data : undefined;
+  const notice  = data && typeof data === 'object' && 'promo_notice' in data
+    ? (data.promo_notice as ICartPromoNotice | null)
+    : null;
+
+  return { message, notice: notice?.reason ? notice : null };
+}