@asteby/storefront 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { GeoPoint } from './geo.js';
 export { OpenStatus, OpeningHours } from './geo.js';
-import { $ as ProductSort, a7 as Shop, Z as ProductConnection, W as Product, q as Connection, p as Collection, G as LocationListParams, L as Location, O as NearestLocation, ab as StockLevel, i as CartLineInput, C as Cart, k as CartLineUpdateInput, d as CartBuyerInput, a as AddressInput, w as DeliveryOptions, U as PaymentMethods, D as DeliveryInput, m as CheckoutInput, o as CheckoutResult, s as CustomerIdentifier, u as CustomerSessionInput, t as CustomerSession, r as Customer, P as Order, a2 as ReturnRequestInput, a1 as ReturnRequest, y as InvoiceRequest, z as InvoiceResult, A as Address, ae as Theme, R as Page, M as Menu, b as Article, ad as StorefrontErrorCode, K as Money } from './types-BmC-RDo8.js';
-export { c as CartBuyer, e as CartCost, f as CartDelivery, g as CartDiscountCode, h as CartLine, j as CartLineMerchandise, l as CheckoutInfo, n as CheckoutPayment, v as DeliveryMethod, F as Facet, x as FacetValue, I as Image, B as LocationContacts, E as LocationKind, H as LocationPickup, J as MenuItem, N as MoneyRange, Q as OrderLine, S as PageInfo, T as PaymentMethod, V as PickupOption, X as ProductAttributeValue, Y as ProductCategory, _ as ProductOption, a0 as ProductVariant, a3 as SEO, a4 as Section, a5 as SelectedOption, a6 as ShippingRate, a8 as ShopBranch, a9 as ShopContact, aa as ShopPolicies, ac as StorefrontErrorBody, af as UnavailableRateProvider } from './types-BmC-RDo8.js';
+import { am as ProductSort, aB as Shop, ak as ProductConnection, ah as Product, x as Connection, w as Collection, S as LocationListParams, P as Location, Y as NearestLocation, aF as StockLevel, at as RestockSubscriptionInput, au as RestockSubscriptionResult, l as CartLineInput, C as Cart, o as CartLineUpdateInput, f as CartBuyerInput, a as AddressInput, H as DeliveryOptions, a9 as PaymentMethods, F as DeliveryInput, as as RecommendationPlacement, r as CartRecommendations, t as CheckoutInput, v as CheckoutResult, ar as PromotionsList, a6 as PaymentConfig, ae as PaymentSubmitInput, a2 as PaymentAttemptResult, z as CustomerIdentifier, D as CustomerSessionInput, B as CustomerSession, y as Customer, Z as Order, aw as ReturnRequestInput, av as ReturnRequest, N as InvoiceRequest, O as InvoiceResult, A as Address, aI as Theme, $ as Page, U as Menu, b as Article, aH as StorefrontErrorCode, M as InsufficientStockLine, W as Money, d as AvailabilityStatus, n as CartLineProblem, c as Availability, an as ProductVariant, E as DeclineCode, af as PaymentVoucher, aa as PaymentNextStep, p as CartPromotions, ap as PromotionReward } from './types-iGGZ9EiC.js';
+export { e as CartBuyer, g as CartCost, h as CartDelivery, i as CartDiscountCode, j as CartDiscountLine, k as CartLine, m as CartLineMerchandise, q as CartRecommendation, s as CheckoutInfo, u as CheckoutPayment, G as DeliveryMethod, I as Facet, J as FacetValue, K as Image, L as InsufficientStockDetails, Q as LocationContacts, R as LocationKind, T as LocationPickup, V as MenuItem, X as MoneyRange, _ as OrderLine, a0 as PageInfo, a1 as PaymentAction, a3 as PaymentAttemptStatus, a4 as PaymentClient, a5 as PaymentClientCsp, a7 as PaymentFlow, a8 as PaymentMethod, ab as PaymentOption, ac as PaymentOptionKey, ad as PaymentPoint, ag as PickupOption, ai as ProductAttributeValue, aj as ProductCategory, al as ProductOption, ao as PromotionAnnouncement, aq as PromotionTier, ax as SEO, ay as Section, az as SelectedOption, aA as ShippingRate, aC as ShopBranch, aD as ShopContact, aE as ShopPolicies, aG as StorefrontErrorBody, aJ as UnavailableRateProvider } from './types-iGGZ9EiC.js';
 
 type QueryValue = string | number | boolean | null | undefined;
 type QueryParams = Record<string, QueryValue | QueryValue[]>;
@@ -77,6 +77,16 @@ type StorefrontClientOptions = {
     locale?: string;
     /** Extra headers on every request. */
     headers?: Record<string, string>;
+    /**
+     * IP address of the shopper, for SERVER-side calls (SSR, route actions) made with an
+     * `sk_`/`pt_` token. Sent as `X-Storefront-Client-IP`, which the gateway honors only for
+     * tokens issued with the `trust_client_ip` option: the rate limit is then charged per
+     * shopper instead of to the store's single token bucket, and the OTP flow limits the
+     * shopper's IP instead of the server's. Pass the IP from your own connection or trusted
+     * proxy, never from a header the browser can forge. Never sent with a `pk_` token (the
+     * gateway already separates those by caller IP). Invalid values are dropped.
+     */
+    clientIp?: string | null;
     /** Abort requests that take longer than this (default: no timeout). */
     timeoutMs?: number;
     /**
@@ -98,6 +108,8 @@ type RequestOptions = {
     timeoutMs?: number;
     /** Overrides the client-level customer token for this call. */
     customerToken?: string | null;
+    /** Overrides the client-level shopper IP for this call (see `StorefrontClientOptions.clientIp`). */
+    clientIp?: string | null;
     [key: string]: unknown;
 };
 type WriteOptions = RequestOptions & {
@@ -118,6 +130,14 @@ type RequestSpec = {
     /** Resolve `null` instead of throwing on 404. */
     nullOn404?: boolean;
 };
+/** Header the gateway reads (only for tokens with `trust_client_ip`). */
+declare const CLIENT_IP_HEADER = "X-Storefront-Client-IP";
+/**
+ * Returns the single IP literal in `raw`, or undefined. Takes the form a server hands over
+ * (`::ffff:1.2.3.4`, `[2001:db8::1]`) and rejects lists, ports, zones and text so the
+ * header is never a forgery vector.
+ */
+declare function normalizeClientIp(raw: string | null | undefined): string | undefined;
 /** Generates an idempotency key (crypto.randomUUID when available). */
 declare function generateIdempotencyKey(): string;
 declare function createStorefrontClient(config: StorefrontClientOptions): {
@@ -132,6 +152,8 @@ declare function createStorefrontClient(config: StorefrontClientOptions): {
     };
     /** Returns a new client that sends the given buyer session token. */
     withCustomerToken(customerToken: string | null): /*elided*/ any;
+    /** Returns a new client that reports the shopper's IP (`X-Storefront-Client-IP`) on every call. */
+    withClientIp(clientIp: string | null | undefined): /*elided*/ any;
     shop: {
         get: (options?: RequestOptions) => Promise<Shop>;
     };
@@ -171,6 +193,13 @@ declare function createStorefrontClient(config: StorefrontClientOptions): {
             nodes: StockLevel[];
         }>;
     };
+    restock: {
+        /**
+         * "Notify me when it is back". Idempotent per contact + SKU; always answers `202 pending`.
+         * Only offered when `availability.notify_available` is true. Needs `customer:write`.
+         */
+        subscribe: (input: RestockSubscriptionInput, options?: WriteOptions) => Promise<RestockSubscriptionResult>;
+    };
     carts: {
         create: (input?: {
             lines?: CartLineInput[];
@@ -188,10 +217,34 @@ declare function createStorefrontClient(config: StorefrontClientOptions): {
         /** Payment providers active for the cart's market; send the chosen `key` as `payment_method`. */
         paymentMethods: (id: string, options?: RequestOptions) => Promise<PaymentMethods>;
         setDelivery: (id: string, delivery: DeliveryInput, options?: WriteOptions) => Promise<Cart>;
+        /** Order note (up to 1000 characters). `null` or empty clears it. */
+        setNote: (id: string, note: string | null, options?: WriteOptions) => Promise<Cart>;
+        /**
+         * Cross-sell suggestions: only sellable variants, with `unlocks` when adding one reaches the next
+         * discount tier. `first` 1-8 (default 4). `private, no-store`; ask on demand, not on every render.
+         */
+        recommendations: (id: string, params?: {
+            first?: number;
+            placement?: RecommendationPlacement;
+        }, options?: RequestOptions) => Promise<CartRecommendations>;
         /** Reserves stock and creates the order. Sends `Idempotency-Key` (auto-generated if omitted). */
         checkout: (id: string, input: CheckoutInput, options?: WriteOptions) => Promise<CheckoutResult>;
     };
+    promotions: {
+        /** Public promotions and the entry pop-up announcement for the request's market (cacheable). */
+        list: (options?: RequestOptions) => Promise<PromotionsList>;
+    };
     checkouts: {
+        /** What to mount for an embedded checkout (public key, options, amount) and whether it can still be paid. Never cache. */
+        paymentConfig: (id: string, options?: RequestOptions) => Promise<PaymentConfig | null>;
+        /**
+         * Pays a checkout in the page. The browser brings only what the provider SDK returned (`provider_data`);
+         * the amount is the server's. `idempotencyKey` is REQUIRED (use `paymentIdempotencyKey(checkoutId, attempt)`):
+         * repeating a call with the same key never charges twice. Needs a server token (`checkout:write`).
+         */
+        pay: (id: string, input: PaymentSubmitInput, options: WriteOptions & {
+            idempotencyKey: string;
+        }) => Promise<PaymentAttemptResult>;
         /**
          * Reads a placed checkout (same shape as the `carts.checkout` result). `order.number` is `null` until OPS
          * has created the order (a few hundred ms after checkout); poll once or twice and, if it is still `null`,
@@ -238,6 +291,8 @@ type StorefrontErrorInit = {
     code: StorefrontErrorCode;
     message: string;
     field?: string;
+    /** Raw `error.details` from the body (untrusted shape). */
+    details?: unknown;
     /** Request URL that failed (without credentials). */
     url?: string;
     cause?: unknown;
@@ -251,8 +306,15 @@ declare class StorefrontError extends Error {
     readonly status: number;
     readonly code: StorefrontErrorCode;
     readonly field: string | undefined;
+    readonly details: unknown;
     readonly url: string | undefined;
     constructor(init: StorefrontErrorInit);
+    /**
+     * Affected lines of a `409 insufficient_stock` (empty for any other error or a
+     * server older than contract 1.1). The cart is untouched: show the lines and
+     * let the buyer adjust or remove them.
+     */
+    get stockLines(): InsufficientStockLine[];
     toJSON(): {
         name: string;
         status: number;
@@ -286,4 +348,229 @@ declare function toMoney(value: number, currencyCode: string): Money;
  */
 declare function isTokenPublishable(token: string | null | undefined): boolean;
 
-export { Address, AddressInput, Article, type ArticleListParams, Cart, CartBuyerInput, CartLineInput, CartLineUpdateInput, CheckoutInput, CheckoutResult, Collection, type CollectionListParams, Connection, Customer, CustomerIdentifier, CustomerSession, CustomerSessionInput, DeliveryInput, DeliveryOptions, type FetchLike, type FormatMoneyOptions, GeoPoint, InvoiceRequest, InvoiceResult, Location, LocationListParams, Menu, Money, NearestLocation, Order, Page, type PaginationParams, PaymentMethods, type PreviewOptions, Product, ProductConnection, type ProductListParams, ProductSort, type QueryParams, type QueryValue, type RequestOptions, ReturnRequest, ReturnRequestInput, Shop, StockLevel, type StorefrontClient, type StorefrontClientOptions, StorefrontError, StorefrontErrorCode, type StorefrontErrorInit, type StorefrontRequestContext, type StorefrontResponseContext, Theme, type WriteOptions, appendParams, createStorefrontClient, formatMoney, generateIdempotencyKey, isStorefrontError, isTokenPublishable, parseMoney, parseProductFilters, productListQuery, toMoney };
+/**
+ * Availability presentation: the single source of the texts and states a
+ * storefront shows for stock. Pure functions, no DOM: safe in loaders, SSR and
+ * edge runtimes.
+ *
+ * The server decides the state (`Availability.status`, already filtered by the
+ * shop's `show_stock`); this module only turns it into labels. Shops may
+ * override texts by key (`messages`) but never the logic. Numbers shown here
+ * ("Quedan 3") come from `availability.quantity`, which the server sends only
+ * when the shop allows it and past its own threshold: there is no threshold in
+ * this code.
+ */
+
+type AvailabilityTone = 'success' | 'warning' | 'danger' | 'info';
+type AvailabilityLocale = 'es' | 'en';
+/** Text keys, overridable per shop. `{n}` and `{date}` are replaced. */
+type AvailabilityMessageKey = 'status.in_stock' | 'status.low_stock' | 'status.low_stock_n' | 'status.out_of_stock' | 'status.backorder' | 'status.preorder' | 'sub.backorder_eta' | 'sub.preorder_date' | 'cta.add' | 'cta.out_of_stock' | 'cta.backorder' | 'cta.preorder' | 'sr.in_stock' | 'sr.low_stock' | 'sr.low_stock_n' | 'sr.out_of_stock' | 'sr.backorder' | 'sr.preorder' | 'option.sold_out' | 'option.backorder' | 'option.preorder' | 'max_per_order' | 'notify.title' | 'notify.email' | 'notify.phone' | 'notify.consent' | 'notify.submit' | 'notify.done' | 'notify.error' | 'problem.out_of_stock' | 'problem.insufficient_stock' | 'problem.insufficient_stock_n' | 'problem.adjust' | 'problem.remove' | 'conflict.title' | 'conflict.body' | 'conflict.dismiss';
+type AvailabilityMessages = Record<AvailabilityMessageKey, string>;
+/** `es-MX` -> `es`, `en-US` -> `en`; anything else falls back to Spanish. */
+declare function availabilityLocale(locale: string | null | undefined): AvailabilityLocale;
+/** Catalog for a locale with the shop's per-key overrides applied. */
+declare function availabilityMessages(locale: string | null | undefined, overrides?: Partial<AvailabilityMessages> | null): AvailabilityMessages;
+/** Replaces `{name}` placeholders. */
+declare function formatAvailabilityMessage(template: string, values?: Record<string, string | number>): string;
+type ResolveAvailabilityOptions = {
+    /**
+     * Polyfill only: shop-level "low stock" threshold to derive `low_stock` from
+     * `quantity_available` on servers older than contract 1.1. Without it the
+     * polyfill never reports `low_stock`. Ignored when the server sends `availability`.
+     */
+    lowStockThreshold?: number | null;
+};
+type AvailabilitySource = Pick<Product | ProductVariant, 'available_for_sale'> & {
+    availability?: Availability | null;
+    quantity_available?: number | null;
+};
+/**
+ * The `Availability` of a variant or product. Uses the server's `availability`
+ * when present; otherwise derives `in_stock | low_stock | out_of_stock` from
+ * `available_for_sale` / `quantity_available` so storefronts can migrate before
+ * the backend does. A malformed `availability` falls back to the polyfill.
+ */
+declare function resolveAvailability(source: AvailabilitySource, options?: ResolveAvailabilityOptions): Availability;
+type AvailabilityView = {
+    status: AvailabilityStatus;
+    tone: AvailabilityTone;
+    /** Short badge text: "Agotado", "Quedan 3", "Bajo pedido"... Never empty. */
+    label: string;
+    /** ETA / release date text, or `null`. */
+    sublabel: string | null;
+    /** Primary button text. */
+    ctaLabel: string;
+    /** The primary button may be pressed (backorder/preorder are purchasable). */
+    ctaEnabled: boolean;
+    /** Offer the "Notify me when it is back" form. */
+    showNotify: boolean;
+    /** Full sentence for screen readers. */
+    srText: string;
+    /** Units to cap the quantity picker at, or `null`. */
+    maxPerOrder: number | null;
+    /** Show a badge on listing cards (everything but plain `in_stock`: do not clutter). */
+    showOnCard: boolean;
+};
+type AvailabilityViewOptions = {
+    messages?: Partial<AvailabilityMessages> | null;
+};
+/**
+ * Texts and flags for one availability. `availability` accepts anything with an
+ * unknown `status` (a future server): it is treated as `out_of_stock`.
+ */
+declare function availabilityView(availability: Availability, locale: string | null | undefined, options?: AvailabilityViewOptions): AvailabilityView;
+type CartLineProblemView = {
+    code: CartLineProblem['code'];
+    /** "Ya no hay existencias" / "Solo puedes llevar 2". */
+    message: string;
+    /** Quantity to adjust the line to, or `null` (remove only). */
+    adjustTo: number | null;
+    adjustLabel: string | null;
+    removeLabel: string;
+};
+/** Texts and actions for a cart line problem. Offers "Adjust to N" only when `max_quantity` is a positive number different from the line quantity (a refused change leaves the cart at its old quantity). */
+declare function cartLineProblemView(problem: CartLineProblem | InsufficientStockLine, locale: string | null | undefined, options?: AvailabilityViewOptions & {
+    lineQuantity?: number;
+}): CartLineProblemView;
+/** schema.org `ItemAvailability` URL for a status (unknown -> `OutOfStock`). */
+declare function schemaAvailability(status: AvailabilityStatus | string): string;
+/** Best state among variants for a product summary (when the server sends none). */
+declare function productAvailability(product: Pick<Product, 'variants' | 'available_for_sale' | 'availability'>, options?: ResolveAvailabilityOptions): Availability;
+
+/**
+ * Embedded payment presentation: the single source of the texts and states a
+ * storefront shows around an in-page payment. Pure functions, no DOM: safe in
+ * loaders, SSR and edge runtimes.
+ *
+ * Rules this module encodes (DISENO-PAGO-INTEGRADO-BRICKS):
+ * - The server decides the outcome and the amount. Nothing here computes or
+ *   compares money; `expected_total` is the server's own number echoed back.
+ * - A rejection is explained with an actionable text built from the neutral
+ *   `decline_code`. A raw provider code is never shown.
+ * - Vouchers and redirects only trust https URLs.
+ */
+
+type PaymentLocale = AvailabilityLocale;
+type PaymentMessageKey = `decline.${DeclineCode}` | 'state.loading' | 'state.processing' | 'state.approved' | 'state.in_review' | 'state.voucher' | 'state.challenge' | 'state.expired' | 'state.cancelled' | 'state.redirect' | 'state.fallback' | 'error.network' | 'error.card_data' | 'error.price_mismatch' | 'error.payment_in_progress' | 'error.expired' | 'error.too_many_attempts' | 'error.generic' | 'action.retry' | 'action.try_again' | 'action.pay' | 'action.cancel' | 'voucher.title' | 'voucher.point' | 'voucher.reference' | 'voucher.amount' | 'voucher.expires' | 'voucher.clabe' | 'voucher.barcode' | 'voucher.open' | 'voucher.email' | 'form.label' | 'challenge.title';
+type PaymentMessages = Record<PaymentMessageKey, string>;
+/** Catalog for a locale (`es-MX` -> es, `en-US` -> en) with the shop's per-key overrides applied. */
+declare function paymentMessages(locale: string | null | undefined, overrides?: Partial<PaymentMessages> | null): PaymentMessages;
+/** i18n key of a decline code; unknown or missing codes map to `declined` (never a raw provider code). */
+declare function declineMessageKey(code: string | null | undefined): `decline.${DeclineCode}`;
+/** Actionable text for a decline code. */
+declare function declineMessage(code: string | null | undefined, locale?: string | null, overrides?: Partial<PaymentMessages> | null): string;
+/** The value only if it is an absolute `https:` URL without credentials; `null` otherwise. */
+declare function safeHttpsUrl(value: unknown): string | null;
+/** What the UI should do with an attempt result. */
+type PaymentOutcomeKind = 'approved' | 'in_review' | 'voucher' | 'challenge' | 'redirect' | 'rejected' | 'expired' | 'cancelled';
+/** A voucher ready to render: https-only link and the amount as `Money` (or `null` when the server sent none). */
+type PaymentOutcomeVoucher = Omit<PaymentVoucher, 'amount' | 'voucher_url' | 'currency'> & {
+    voucher_url: string | null;
+    amount: Money | null;
+};
+type PaymentOutcome = {
+    kind: PaymentOutcomeKind;
+    /** Text for the buyer (no codes). */
+    message: string;
+    decline_code: DeclineCode | null;
+    /** `true` when the buyer can try again with the checkout still open. */
+    retryable: boolean;
+    /** https-only. */
+    redirect_url: string | null;
+    challenge: {
+        url: string | null;
+        creq: string | null;
+    } | null;
+    voucher: PaymentOutcomeVoucher | null;
+    attempts_left: number | null;
+    /** What to do next (server value, or derived from the decline code): fix the card, use another, rebuild the cart... */
+    next_step: PaymentNextStep | null;
+};
+/**
+ * Classifies an attempt result. Unknown statuses are treated as `in_review`
+ * (never as approved, never as a reason to charge again).
+ */
+declare function paymentOutcome(result: PaymentAttemptResult, locale?: string | null, overrides?: Partial<PaymentMessages> | null): PaymentOutcome;
+/** Failures of `POST /payment` the form maps to a specific text and next step. */
+type PaymentErrorKind = 'network' | 'price_mismatch' | 'payment_in_progress' | 'expired' | 'too_many_attempts' | 'generic';
+type PaymentErrorView = {
+    kind: PaymentErrorKind;
+    message: string;
+    retrySameAttempt: boolean;
+    canRetry: boolean;
+};
+/**
+ * Maps a transport error (a `StorefrontError` or anything with `status`/`code`)
+ * to a view. Network failures and 502/503/504 are safe to retry with the same
+ * idempotency key; 409/422/429 are answers, not outages.
+ */
+declare function paymentErrorView(err: unknown, locale?: string | null, overrides?: Partial<PaymentMessages> | null): PaymentErrorView;
+/** `Vence el 5 de noviembre de 2026, 18:00` style text for a voucher deadline; `null` when absent or invalid. */
+declare function formatVoucherExpiry(expiresAt: string | null | undefined, locale?: string | null, overrides?: Partial<PaymentMessages> | null): string | null;
+/** Builds an idempotency key for a payment attempt: the same attempt always yields the same key. */
+declare function paymentIdempotencyKey(checkoutId: string, attempt: string): string;
+
+/**
+ * Promotion presentation: turns `Cart.promotions` (computed by OPS) into the
+ * labels and bar states a storefront shows. Pure functions, no DOM.
+ *
+ * The shop never computes a discount here: `remaining`, `percent`, `reached`
+ * and `percent_of_max` are the server's. The only arithmetic is clamping a
+ * server percentage into 0-100 for `aria-valuenow`.
+ */
+
+type PromotionLocale = AvailabilityLocale;
+type PromotionMessageKey = 'discount.next' | 'discount.next_upgrade' | 'discount.applied' | 'discount.max' | 'discount.suppressed' | 'discount.unlocks' | 'discount.remaining' | 'shipping.progress' | 'shipping.reached' | 'shipping.always' | 'reward.free_shipping' | 'bar.discount' | 'bar.shipping' | 'popup.close' | 'popup.valid_until' | 'popup.limited_time' | 'popup.discount_tier' | 'popup.free_shipping_min' | 'popup.free_shipping_always' | 'upsell.title' | 'upsell.subtitle' | 'upsell.next_level' | 'upsell.you_miss' | 'upsell.unlocks_reward' | 'upsell.total_saved' | 'upsell.current_benefit' | 'upsell.status' | 'upsell.status_pending' | 'upsell.status_active' | 'upsell.next_reward' | 'upsell.suggestions' | 'upsell.add' | 'upsell.adding' | 'upsell.flavor' | 'upsell.unlocks_badge' | 'upsell.unlocked' | 'upsell.best' | 'upsell.skip' | 'upsell.continue' | 'upsell.footer' | 'upsell.sold_out' | 'upsell.error' | 'note.label' | 'note.placeholder' | 'note.save' | 'note.saving' | 'note.saved' | 'note.error' | 'note.counter';
+type PromotionMessages = Record<PromotionMessageKey, string>;
+/** Catalog for a locale with the shop's per-key overrides applied. */
+declare function promotionMessages(locale: string | null | undefined, overrides?: Partial<PromotionMessages> | null): PromotionMessages;
+/** Order-note limit enforced by the server (`validateNote`). */
+declare const NOTE_MAX_LENGTH = 1000;
+/** Trims and caps a note; empty becomes `null` (the server clears the note). */
+declare function normalizeNote(note: string | null | undefined): string | null;
+/** `5 %` / `7.5 %` (es) or `5%` (en) / `$250` / `Envío gratis`. The values are the server's. */
+declare function rewardLabel(reward: PromotionReward, locale?: string | null, overrides?: Partial<PromotionMessages> | null): string;
+/** Display clamp for a server percentage (`aria-valuenow`). Not a calculation. */
+declare function clampPercent(value: unknown): number;
+type DiscountBarState = 'next' | 'upgrade' | 'max' | 'suppressed';
+type DiscountBarView = {
+    state: DiscountBarState;
+    /** Server progress 0-100. */
+    percent: number;
+    text: string;
+    /** `aria-valuetext`. */
+    valueText: string;
+    remaining: Money | null;
+    /** Reward of the next tier (or the applied one at max). */
+    rewardText: string | null;
+    appliedText: string | null;
+    nextText: string | null;
+    tiers: {
+        id: string;
+        label: string;
+        threshold: string;
+        reached: boolean;
+        position: number;
+    }[];
+};
+type ShippingBarState = 'progress' | 'reached' | 'always';
+type ShippingBarView = {
+    state: ShippingBarState;
+    percent: number;
+    text: string;
+    valueText: string;
+    remaining: Money | null;
+    /** `false` for `always`: there is nothing to fill. */
+    showBar: boolean;
+};
+type PromoProgressView = {
+    discount: DiscountBarView | null;
+    shipping: ShippingBarView | null;
+};
+/**
+ * Bars of the cart and the pre-payment modal. Both read the same `Cart.promotions`,
+ * so they can never disagree. `null`/absent promotions give `{ discount: null, shipping: null }`.
+ */
+declare function promoProgressView(promotions: CartPromotions | null | undefined, locale?: string | null, overrides?: Partial<PromotionMessages> | null): PromoProgressView;
+
+export { Address, AddressInput, Article, type ArticleListParams, Availability, type AvailabilityLocale, type AvailabilityMessageKey, type AvailabilityMessages, AvailabilityStatus, type AvailabilityTone, type AvailabilityView, type AvailabilityViewOptions, CLIENT_IP_HEADER, Cart, CartBuyerInput, CartLineInput, CartLineProblem, type CartLineProblemView, CartLineUpdateInput, CartPromotions, CartRecommendations, CheckoutInput, CheckoutResult, Collection, type CollectionListParams, Connection, Customer, CustomerIdentifier, CustomerSession, CustomerSessionInput, DeclineCode, DeliveryInput, DeliveryOptions, type DiscountBarState, type DiscountBarView, type FetchLike, type FormatMoneyOptions, GeoPoint, InsufficientStockLine, InvoiceRequest, InvoiceResult, Location, LocationListParams, Menu, Money, NOTE_MAX_LENGTH, NearestLocation, Order, Page, type PaginationParams, PaymentAttemptResult, PaymentConfig, type PaymentErrorKind, type PaymentErrorView, type PaymentLocale, type PaymentMessageKey, type PaymentMessages, PaymentMethods, PaymentNextStep, type PaymentOutcome, type PaymentOutcomeKind, PaymentSubmitInput, PaymentVoucher, type PreviewOptions, Product, ProductConnection, type ProductListParams, ProductSort, ProductVariant, type PromoProgressView, type PromotionLocale, type PromotionMessageKey, type PromotionMessages, PromotionReward, PromotionsList, type QueryParams, type QueryValue, RecommendationPlacement, type RequestOptions, type ResolveAvailabilityOptions, RestockSubscriptionInput, RestockSubscriptionResult, ReturnRequest, ReturnRequestInput, type ShippingBarState, type ShippingBarView, Shop, StockLevel, type StorefrontClient, type StorefrontClientOptions, StorefrontError, StorefrontErrorCode, type StorefrontErrorInit, type StorefrontRequestContext, type StorefrontResponseContext, Theme, type WriteOptions, appendParams, availabilityLocale, availabilityMessages, availabilityView, cartLineProblemView, clampPercent, createStorefrontClient, declineMessage, declineMessageKey, formatAvailabilityMessage, formatMoney, formatVoucherExpiry, generateIdempotencyKey, isStorefrontError, isTokenPublishable, normalizeClientIp, normalizeNote, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, productAvailability, productListQuery, promoProgressView, promotionMessages, resolveAvailability, rewardLabel, safeHttpsUrl, schemaAvailability, toMoney };