@asteby/storefront 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { GeoPoint } from './geo.cjs';
 export { OpenStatus, OpeningHours } from './geo.cjs';
-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-D300wdPF.cjs';
-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-D300wdPF.cjs';
+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-CSMuPSQA.cjs';
+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-CSMuPSQA.cjs';
 
 type QueryValue = string | number | boolean | null | undefined;
 type QueryParams = Record<string, QueryValue | QueryValue[]>;
@@ -75,6 +75,18 @@ type StorefrontClientOptions = {
     fetch?: FetchLike;
     /** Sent as `Accept-Language`. */
     locale?: string;
+    /**
+     * Public host of the storefront (`godsnutrition.com`), sent as `X-Storefront-Domain`. Platform (`pt_`)
+     * tokens need it to pick the organization; with an org-scoped token it only scopes the market.
+     */
+    domain?: string;
+    /**
+     * Market the request is for (`mx`, `us`), sent as `<domain>#<market>` in `X-Storefront-Domain`. It lets ONE
+     * public domain serve several markets (the storefront routes by path prefix, e.g. `/us`): OPS honors it
+     * when the organization has that market active and otherwise falls back to the domain's own market.
+     * Ignored without `domain`.
+     */
+    market?: string;
     /** Extra headers on every request. */
     headers?: Record<string, string>;
     /**
@@ -193,6 +205,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[];
@@ -210,10 +229,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`,
@@ -254,12 +297,16 @@ declare function createStorefrontClient(config: StorefrontClientOptions): {
     };
 };
 type StorefrontClient = ReturnType<typeof createStorefrontClient>;
+/** `X-Storefront-Domain` value: the host, plus `#<market>` when a valid market code is given. */
+declare function storefrontDomainHeader(domain: string, market?: string | null): string;
 
 type StorefrontErrorInit = {
     status: number;
     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;
@@ -273,8 +320,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;
@@ -308,4 +362,288 @@ declare function toMoney(value: number, currencyCode: string): Money;
  */
 declare function isTokenPublishable(token: string | null | undefined): boolean;
 
-export { Address, AddressInput, Article, type ArticleListParams, CLIENT_IP_HEADER, 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, normalizeClientIp, 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;
+
+/**
+ * Detección de mercado por visita (país + idioma), pura y sin DOM: sirve en el servidor de cualquier tienda.
+ *
+ * Reglas (mejores prácticas de i18n para comercio):
+ * - El mercado canónico lo fija el DOMINIO (OPS liga cada dominio verificado a un mercado: org_domains.market_code).
+ *   Esto no lo decide la geolocalización: así cada URL tiene un solo idioma/moneda (SEO, hreflang, caché de CDN).
+ * - La geolocalización solo SUGIERE (banner "¿Ver la tienda de Estados Unidos?"); nunca redirige sola, nunca a rastreadores
+ *   y respeta la elección guardada del comprador.
+ * - Precios, impuestos y envío NO dependen de la IP: dependen del mercado del dominio y de la dirección de entrega.
+ * - El país sale de las cabeceras que pone el CDN/proxy (no se puede confiar en ellas si el servidor está expuesto
+ *   directo a internet: solo se leen con `trustProxy`).
+ */
+type MarketInfo = {
+    /** Código del mercado en OPS ("mx", "us"). */
+    code: string;
+    /** ISO 3166-1 alfa-2 a los que vende. */
+    countries: string[];
+    /** BCP 47 por defecto ("es-MX", "en-US"). */
+    locale: string;
+    /** ISO 4217 ("MXN", "USD"). */
+    currency: string;
+    /** Dominio público del mercado, si es distinto del actual ("godsnutrition.com"). */
+    host?: string;
+};
+/** Cabeceras de país de los CDN/proxies más comunes, en orden de preferencia. */
+declare const COUNTRY_HEADERS: readonly ["cf-ipcountry", "cloudfront-viewer-country", "x-vercel-ip-country", "x-appengine-country", "x-country-code"];
+/** País del visitante según el CDN. `null` si no viene, es desconocido (XX), Tor (T1) o no es ISO alfa-2. */
+declare function visitorCountry(headers: Headers, { trustProxy }?: {
+    trustProxy?: boolean;
+}): string | null;
+/** Idiomas de Accept-Language ordenados por q (mayor primero), en minúsculas. */
+declare function preferredLanguages(acceptLanguage: string | null | undefined): string[];
+/** Mejor idioma entre los que ofrece la tienda: coincidencia exacta, luego por idioma base; si no, el de `fallback`. */
+declare function negotiateLocale(acceptLanguage: string | null | undefined, available: string[], fallback: string): string;
+type MarketSuggestion = {
+    market: MarketInfo;
+    /** Qué disparó la sugerencia. El país manda; el idioma solo si el CDN no dio país. */
+    reason: 'country' | 'language';
+};
+/**
+ * ¿Conviene sugerir otro mercado a esta visita? `null` si no (ya está en el correcto, rastreador, ya eligió, o no hay otro).
+ * `chosen` es el código que el comprador guardó al elegir a mano ("market" en cookie): si existe, no se vuelve a sugerir.
+ */
+declare function suggestMarket({ headers, markets, current, chosen, trustProxy, }: {
+    headers: Headers;
+    markets: MarketInfo[];
+    current: string;
+    chosen?: string | null;
+    trustProxy?: boolean;
+}): MarketSuggestion | null;
+/**
+ * Enlaces `hreflang` para <head>: un alterno por mercado con dominio propio, más x-default (el mercado por defecto).
+ * `path` es la ruta con query actual ("/productos/x"). Es lo que permite a buscadores servir cada país en su idioma.
+ */
+declare function hreflangLinks(markets: MarketInfo[], path: string, defaultMarket: string, protocol?: string): {
+    hrefLang: string;
+    href: string;
+}[];
+
+export { Address, AddressInput, Article, type ArticleListParams, Availability, type AvailabilityLocale, type AvailabilityMessageKey, type AvailabilityMessages, AvailabilityStatus, type AvailabilityTone, type AvailabilityView, type AvailabilityViewOptions, CLIENT_IP_HEADER, COUNTRY_HEADERS, 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, type MarketInfo, type MarketSuggestion, 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, hreflangLinks, isStorefrontError, isTokenPublishable, negotiateLocale, normalizeClientIp, normalizeNote, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, preferredLanguages, productAvailability, productListQuery, promoProgressView, promotionMessages, resolveAvailability, rewardLabel, safeHttpsUrl, schemaAvailability, storefrontDomainHeader, suggestMarket, toMoney, visitorCountry };