@asteby/storefront 0.11.1 → 0.12.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { GeoPoint } from './geo.cjs';
 export { OpenStatus, OpeningHours } from './geo.cjs';
-import { aJ as ProductSort, b8 as TokenIntrospection, b0 as Shop, aQ as Region, aH as ProductConnection, aE as Product, y as Connection, x as Collection, ad as LocationListParams, aa as Location, aj as NearestLocation, b4 as StockLevel, aU as RestockSubscriptionInput, aV as RestockSubscriptionResult, m as CartLineInput, C as Cart, p as CartLineUpdateInput, f as CartBuyerInput, a as AddressInput, Q as DeliveryOptions, aw as PaymentMethods, O as DeliveryInput, a5 as InvoiceRequest, aP as RecommendationPlacement, s as CartRecommendations, u as CheckoutInput, w as CheckoutResult, aO as PromotionsList, at as PaymentConfig, aB as PaymentSubmitInput, ap as PaymentAttemptResult, D as CustomerIdentifier, J as CustomerSessionInput, I as CustomerSession, B as CustomerCapabilities, F as CustomerRegisterInput, G as CustomerRegisterResult, M as CustomerVerifyRegistrationInput, E as CustomerPasswordLoginInput, K as CustomerSetPasswordInput, H as CustomerResetPasswordInput, z as Customer, L as CustomerUpdateInput, ak as Order, aX as ReturnRequestInput, aW as ReturnRequest, a6 as InvoiceResult, A as Address, b7 as Theme, am as Page, af as Menu, b as Article, b6 as StorefrontErrorCode, a3 as InsufficientStockLine, ah as Money, d as AvailabilityStatus, o as CartLineProblem, c as Availability, aK as ProductVariant, N as DeclineCode, aC as PaymentVoucher, ax as PaymentNextStep, q as CartPromotions, aM as PromotionReward, P as DeliveryMethod, b9 as UnavailableRateProvider } from './types-bsdlAumU.cjs';
-export { e as CartBuyer, g as CartCost, h as CartDelivery, i as CartDiscountCode, j as CartDiscountLine, k as CartInvoice, l as CartLine, n as CartLineMerchandise, r as CartRecommendation, t as CheckoutInfo, v as CheckoutPayment, R as Facet, S as FacetValue, T as FiscalDocumentEvidence, U as FiscalDocumentSource, V as FiscalIdentity, W as FiscalIdentityInput, X as FiscalVerification, Y as IdentityCapture, Z as IdentityDocumentSpec, _ as IdentityFieldRule, $ as IdentityRulesV1, a0 as IdentityStrategy, a1 as Image, a2 as InsufficientStockDetails, a4 as InvoiceAction, a7 as InvoiceStage, a8 as InvoiceSummary, a9 as InvoicingCapabilities, ab as LocationContacts, ac as LocationKind, ae as LocationPickup, ag as MenuItem, ai as MoneyRange, al as OrderLine, an as PageInfo, ao as PaymentAction, aq as PaymentAttemptStatus, ar as PaymentClient, as as PaymentClientCsp, au as PaymentFlow, av as PaymentMethod, ay as PaymentOption, az as PaymentOptionKey, aA as PaymentPoint, aD as PickupOption, aF as ProductAttributeValue, aG as ProductCategory, aI as ProductOption, aL as PromotionAnnouncement, aN as PromotionTier, aR as RegionFiscalEntry, aS as RegionFiscalId, aT as RegionPaymentMethod, aY as SEO, aZ as Section, a_ as SelectedOption, a$ as ShippingRate, b1 as ShopBranch, b2 as ShopContact, b3 as ShopPolicies, b5 as StorefrontErrorBody } from './types-bsdlAumU.cjs';
+import { aJ as ProductSort, b8 as TokenIntrospection, b0 as Shop, aQ as Region, aH as ProductConnection, aE as Product, y as Connection, x as Collection, ad as LocationListParams, aa as Location, aj as NearestLocation, b4 as StockLevel, aU as RestockSubscriptionInput, aV as RestockSubscriptionResult, m as CartLineInput, C as Cart, p as CartLineUpdateInput, f as CartBuyerInput, a as AddressInput, Q as DeliveryOptions, aw as PaymentMethods, O as DeliveryInput, a5 as InvoiceRequest, aP as RecommendationPlacement, s as CartRecommendations, u as CheckoutInput, w as CheckoutResult, aO as PromotionsList, at as PaymentConfig, aB as PaymentSubmitInput, ap as PaymentAttemptResult, D as CustomerIdentifier, J as CustomerSessionInput, I as CustomerSession, B as CustomerCapabilities, F as CustomerRegisterInput, G as CustomerRegisterResult, M as CustomerVerifyRegistrationInput, E as CustomerPasswordLoginInput, K as CustomerSetPasswordInput, H as CustomerResetPasswordInput, z as Customer, L as CustomerUpdateInput, ak as Order, aX as ReturnRequestInput, aW as ReturnRequest, a6 as InvoiceResult, A as Address, b7 as Theme, am as Page, af as Menu, b as Article, b6 as StorefrontErrorCode, a3 as InsufficientStockLine, ah as Money, d as AvailabilityStatus, o as CartLineProblem, c as Availability, aK as ProductVariant, N as DeclineCode, aC as PaymentVoucher, ax as PaymentNextStep, q as CartPromotions, aM as PromotionReward, P as DeliveryMethod, b9 as UnavailableRateProvider } from './types-BQ3S6VjF.cjs';
+export { e as CartBuyer, g as CartCost, h as CartDelivery, i as CartDiscountCode, j as CartDiscountLine, k as CartInvoice, l as CartLine, n as CartLineMerchandise, r as CartRecommendation, t as CheckoutInfo, v as CheckoutPayment, R as Facet, S as FacetValue, T as FiscalDocumentEvidence, U as FiscalDocumentSource, V as FiscalIdentity, W as FiscalIdentityInput, X as FiscalVerification, Y as IdentityCapture, Z as IdentityDocumentSpec, _ as IdentityFieldRule, $ as IdentityRulesV1, a0 as IdentityStrategy, a1 as Image, a2 as InsufficientStockDetails, a4 as InvoiceAction, a7 as InvoiceStage, a8 as InvoiceSummary, a9 as InvoicingCapabilities, ab as LocationContacts, ac as LocationKind, ae as LocationPickup, ag as MenuItem, ai as MoneyRange, al as OrderLine, an as PageInfo, ao as PaymentAction, aq as PaymentAttemptStatus, ar as PaymentClient, as as PaymentClientCsp, au as PaymentFlow, av as PaymentMethod, ay as PaymentOption, az as PaymentOptionKey, aA as PaymentPoint, aD as PickupOption, aF as ProductAttributeValue, aG as ProductCategory, aI as ProductOption, aL as PromotionAnnouncement, aN as PromotionTier, aR as RegionFiscalEntry, aS as RegionFiscalId, aT as RegionPaymentMethod, aY as SEO, aZ as Section, a_ as SelectedOption, a$ as ShippingRate, b1 as ShopBranch, b2 as ShopContact, b3 as ShopPolicies, b5 as StorefrontErrorBody } from './types-BQ3S6VjF.cjs';
 
 type QueryValue = string | number | boolean | null | undefined;
 type QueryParams = Record<string, QueryValue | QueryValue[]>;
@@ -353,6 +353,16 @@ type StorefrontErrorInit = {
     cause?: unknown;
     /** Scopes named by the gateway on a `403 insufficient_scope`. */
     requiredScopes?: string[];
+    /** `error.retryable` as OPS declared it (payment failures). `undefined` = OPS did not say. */
+    retryable?: boolean;
+    /** `error.retry_after` in seconds. */
+    retryAfter?: number;
+    /** `error.checkout_id`: the checkout a refused cart write can resume. */
+    checkoutId?: string;
+    /** `error.cost` of a `price_mismatch` (the cart's current cost; untrusted shape). */
+    cost?: unknown;
+    /** `error.message_en`. */
+    messageEn?: string;
 };
 /**
  * Error thrown by the client for any non-2xx response, network failure,
@@ -367,6 +377,16 @@ declare class StorefrontError extends Error {
     readonly url: string | undefined;
     /** Scopes a `403 insufficient_scope` says the route needs (empty for any other error). */
     readonly requiredScopes: string[];
+    /** `true`: repeating the request (same idempotency key) can succeed. `false`: not until someone fixes something. `undefined`: OPS did not say. */
+    readonly retryable: boolean | undefined;
+    /** Seconds OPS asks to wait before retrying. */
+    readonly retryAfter: number | undefined;
+    /** Checkout that a refused cart write can resume. */
+    readonly checkoutId: string | undefined;
+    /** Current cart cost sent with a `price_mismatch` (untrusted shape). */
+    readonly cost: unknown;
+    /** English version of `message`, when OPS sent one. */
+    readonly messageEn: string | undefined;
     constructor(init: StorefrontErrorInit);
     /**
      * Affected lines of a `409 insufficient_stock` (empty for any other error or a
@@ -375,6 +395,9 @@ declare class StorefrontError extends Error {
      */
     get stockLines(): InsufficientStockLine[];
     toJSON(): {
+        checkoutId?: string | undefined;
+        retryAfter?: number | undefined;
+        retryable?: boolean | undefined;
         requiredScopes?: string[] | undefined;
         name: string;
         status: number;
@@ -385,6 +408,52 @@ declare class StorefrontError extends Error {
 }
 declare function isStorefrontError(err: unknown): err is StorefrontError;
 
+/**
+ * Classification of the failures of a card payment (`POST pay` / `GET status`). No texts, no DOM, no server APIs: the
+ * shop's server uses it to answer with `kind` and `retryable`, and the browser transport uses it to decide whether to
+ * repeat, ask for the status or give up.
+ *
+ * Rule that never changes: an INDETERMINATE result (`transient`, `in_progress`) is never charged again with another
+ * idempotency key; it is repeated with the SAME key or its status is read.
+ */
+type PaymentErrorClassKind = 
+/** OPS or the provider did not answer (5xx, timeout, network). The charge may or may not have happened. */
+'transient'
+/** A payment is already in progress for this order (409): read the status, do not charge again. */
+ | 'in_progress'
+/** Too many attempts (429). */
+ | 'rate_limited'
+/** Credentials or configuration of the merchant with the provider: not the buyer's fault. */
+ | 'merchant_config'
+/** The provider refused the charge at API level (`payment_provider_rejected`): definitive, nothing was charged. */
+ | 'provider_declined'
+/** The cart already became an order and OPS will not open a new attempt (`422 invalid_state`). */
+ | 'stale_checkout' | 'expired' | 'price_mismatch' | 'store_closed' | 'validation' | 'other';
+type PaymentErrorClass = {
+    kind: PaymentErrorClassKind;
+    retryable: boolean;
+};
+type PaymentErrorLike = {
+    status?: number | null;
+    code?: string | null;
+    field?: string | null;
+    /** `error.retryable` as OPS declared it (`StorefrontError.retryable`). */
+    retryable?: boolean | null;
+    /** `error.checkout_id` (`StorefrontError.checkoutId`). */
+    checkoutId?: string | null;
+    /** Raw `error.details`; a `retryable` inside is honoured too (older bodies). */
+    details?: unknown;
+};
+/** Did OPS expressly say the failure must NOT be repeated (`retryable: false`, on the error or inside `details`)? */
+declare function opsSaysNotRetryable(err: PaymentErrorLike): boolean;
+/** Field the shop's server sets when IT refuses a payment row that is not offered (so it is not read as a stale checkout). */
+declare const PAYMENT_CHOICE_REFUSED_FIELD = "payment_choice";
+/**
+ * What a payment failure means and whether repeating it can help. What OPS declares (`retryable`, stable codes) wins
+ * over the HTTP status: a 502 with a stable code is an answer, not "no response".
+ */
+declare function classifyPaymentError(err: PaymentErrorLike): PaymentErrorClass;
+
 /** `sk_…a91f`: the prefix and the last four characters, never enough to use the token. */
 declare function maskToken(token: string | null | undefined): string;
 type DiagnoseOptions = {
@@ -748,4 +817,4 @@ type DeliveryNotices = {
 /** Splits `delivery.unavailable` into the `missing_weight` notice and the generic one. */
 declare function deliveryNotices(delivery: Pick<DeliveryOptions, 'unavailable' | 'partial'> | null | undefined): DeliveryNotices;
 
-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, CustomerCapabilities, CustomerIdentifier, CustomerPasswordLoginInput, CustomerRegisterInput, CustomerRegisterResult, CustomerResetPasswordInput, CustomerSession, CustomerSessionInput, CustomerSetPasswordInput, CustomerUpdateInput, CustomerVerifyRegistrationInput, DeclineCode, type DeliveryChoice, type DeliveryChoiceKind, DeliveryInput, DeliveryMethod, type DeliveryNotices, DeliveryOptions, type DiagnoseOptions, type DiscountBarState, type DiscountBarView, type FetchLike, type FormatMoneyOptions, GeoPoint, InsufficientStockLine, InvoiceRequest, InvoiceResult, Location, LocationListParams, MISSING_WEIGHT, 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, Region, 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, TokenIntrospection, UnavailableRateProvider, type WriteOptions, appendParams, availabilityLocale, availabilityMessages, availabilityView, cartLineProblemView, clampPercent, createStorefrontClient, declineMessage, declineMessageKey, deliveryInput, deliveryNotices, diagnose, formatAvailabilityMessage, formatMoney, formatVoucherExpiry, generateIdempotencyKey, hreflangLinks, isStorefrontError, isTokenPublishable, maskToken, negotiateLocale, normalizeClientIp, normalizeNote, parseDelivery, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, preferredLanguages, productAvailability, productListQuery, promoProgressView, promotionMessages, repairPath, resolveAvailability, rewardLabel, safeHttpsUrl, schemaAvailability, storefrontDomainHeader, suggestMarket, toMoney, visitorCountry };
+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, CustomerCapabilities, CustomerIdentifier, CustomerPasswordLoginInput, CustomerRegisterInput, CustomerRegisterResult, CustomerResetPasswordInput, CustomerSession, CustomerSessionInput, CustomerSetPasswordInput, CustomerUpdateInput, CustomerVerifyRegistrationInput, DeclineCode, type DeliveryChoice, type DeliveryChoiceKind, DeliveryInput, DeliveryMethod, type DeliveryNotices, DeliveryOptions, type DiagnoseOptions, type DiscountBarState, type DiscountBarView, type FetchLike, type FormatMoneyOptions, GeoPoint, InsufficientStockLine, InvoiceRequest, InvoiceResult, Location, LocationListParams, MISSING_WEIGHT, type MarketInfo, type MarketSuggestion, Menu, Money, NOTE_MAX_LENGTH, NearestLocation, Order, PAYMENT_CHOICE_REFUSED_FIELD, Page, type PaginationParams, PaymentAttemptResult, PaymentConfig, type PaymentErrorClass, type PaymentErrorClassKind, type PaymentErrorKind, type PaymentErrorLike, 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, Region, 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, TokenIntrospection, UnavailableRateProvider, type WriteOptions, appendParams, availabilityLocale, availabilityMessages, availabilityView, cartLineProblemView, clampPercent, classifyPaymentError, createStorefrontClient, declineMessage, declineMessageKey, deliveryInput, deliveryNotices, diagnose, formatAvailabilityMessage, formatMoney, formatVoucherExpiry, generateIdempotencyKey, hreflangLinks, isStorefrontError, isTokenPublishable, maskToken, negotiateLocale, normalizeClientIp, normalizeNote, opsSaysNotRetryable, parseDelivery, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, preferredLanguages, productAvailability, productListQuery, promoProgressView, promotionMessages, repairPath, resolveAvailability, rewardLabel, safeHttpsUrl, schemaAvailability, storefrontDomainHeader, suggestMarket, toMoney, visitorCountry };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { GeoPoint } from './geo.js';
 export { OpenStatus, OpeningHours } from './geo.js';
-import { aJ as ProductSort, b8 as TokenIntrospection, b0 as Shop, aQ as Region, aH as ProductConnection, aE as Product, y as Connection, x as Collection, ad as LocationListParams, aa as Location, aj as NearestLocation, b4 as StockLevel, aU as RestockSubscriptionInput, aV as RestockSubscriptionResult, m as CartLineInput, C as Cart, p as CartLineUpdateInput, f as CartBuyerInput, a as AddressInput, Q as DeliveryOptions, aw as PaymentMethods, O as DeliveryInput, a5 as InvoiceRequest, aP as RecommendationPlacement, s as CartRecommendations, u as CheckoutInput, w as CheckoutResult, aO as PromotionsList, at as PaymentConfig, aB as PaymentSubmitInput, ap as PaymentAttemptResult, D as CustomerIdentifier, J as CustomerSessionInput, I as CustomerSession, B as CustomerCapabilities, F as CustomerRegisterInput, G as CustomerRegisterResult, M as CustomerVerifyRegistrationInput, E as CustomerPasswordLoginInput, K as CustomerSetPasswordInput, H as CustomerResetPasswordInput, z as Customer, L as CustomerUpdateInput, ak as Order, aX as ReturnRequestInput, aW as ReturnRequest, a6 as InvoiceResult, A as Address, b7 as Theme, am as Page, af as Menu, b as Article, b6 as StorefrontErrorCode, a3 as InsufficientStockLine, ah as Money, d as AvailabilityStatus, o as CartLineProblem, c as Availability, aK as ProductVariant, N as DeclineCode, aC as PaymentVoucher, ax as PaymentNextStep, q as CartPromotions, aM as PromotionReward, P as DeliveryMethod, b9 as UnavailableRateProvider } from './types-B1E3GySa.js';
-export { e as CartBuyer, g as CartCost, h as CartDelivery, i as CartDiscountCode, j as CartDiscountLine, k as CartInvoice, l as CartLine, n as CartLineMerchandise, r as CartRecommendation, t as CheckoutInfo, v as CheckoutPayment, R as Facet, S as FacetValue, T as FiscalDocumentEvidence, U as FiscalDocumentSource, V as FiscalIdentity, W as FiscalIdentityInput, X as FiscalVerification, Y as IdentityCapture, Z as IdentityDocumentSpec, _ as IdentityFieldRule, $ as IdentityRulesV1, a0 as IdentityStrategy, a1 as Image, a2 as InsufficientStockDetails, a4 as InvoiceAction, a7 as InvoiceStage, a8 as InvoiceSummary, a9 as InvoicingCapabilities, ab as LocationContacts, ac as LocationKind, ae as LocationPickup, ag as MenuItem, ai as MoneyRange, al as OrderLine, an as PageInfo, ao as PaymentAction, aq as PaymentAttemptStatus, ar as PaymentClient, as as PaymentClientCsp, au as PaymentFlow, av as PaymentMethod, ay as PaymentOption, az as PaymentOptionKey, aA as PaymentPoint, aD as PickupOption, aF as ProductAttributeValue, aG as ProductCategory, aI as ProductOption, aL as PromotionAnnouncement, aN as PromotionTier, aR as RegionFiscalEntry, aS as RegionFiscalId, aT as RegionPaymentMethod, aY as SEO, aZ as Section, a_ as SelectedOption, a$ as ShippingRate, b1 as ShopBranch, b2 as ShopContact, b3 as ShopPolicies, b5 as StorefrontErrorBody } from './types-B1E3GySa.js';
+import { aJ as ProductSort, b8 as TokenIntrospection, b0 as Shop, aQ as Region, aH as ProductConnection, aE as Product, y as Connection, x as Collection, ad as LocationListParams, aa as Location, aj as NearestLocation, b4 as StockLevel, aU as RestockSubscriptionInput, aV as RestockSubscriptionResult, m as CartLineInput, C as Cart, p as CartLineUpdateInput, f as CartBuyerInput, a as AddressInput, Q as DeliveryOptions, aw as PaymentMethods, O as DeliveryInput, a5 as InvoiceRequest, aP as RecommendationPlacement, s as CartRecommendations, u as CheckoutInput, w as CheckoutResult, aO as PromotionsList, at as PaymentConfig, aB as PaymentSubmitInput, ap as PaymentAttemptResult, D as CustomerIdentifier, J as CustomerSessionInput, I as CustomerSession, B as CustomerCapabilities, F as CustomerRegisterInput, G as CustomerRegisterResult, M as CustomerVerifyRegistrationInput, E as CustomerPasswordLoginInput, K as CustomerSetPasswordInput, H as CustomerResetPasswordInput, z as Customer, L as CustomerUpdateInput, ak as Order, aX as ReturnRequestInput, aW as ReturnRequest, a6 as InvoiceResult, A as Address, b7 as Theme, am as Page, af as Menu, b as Article, b6 as StorefrontErrorCode, a3 as InsufficientStockLine, ah as Money, d as AvailabilityStatus, o as CartLineProblem, c as Availability, aK as ProductVariant, N as DeclineCode, aC as PaymentVoucher, ax as PaymentNextStep, q as CartPromotions, aM as PromotionReward, P as DeliveryMethod, b9 as UnavailableRateProvider } from './types-C_rsJRCl.js';
+export { e as CartBuyer, g as CartCost, h as CartDelivery, i as CartDiscountCode, j as CartDiscountLine, k as CartInvoice, l as CartLine, n as CartLineMerchandise, r as CartRecommendation, t as CheckoutInfo, v as CheckoutPayment, R as Facet, S as FacetValue, T as FiscalDocumentEvidence, U as FiscalDocumentSource, V as FiscalIdentity, W as FiscalIdentityInput, X as FiscalVerification, Y as IdentityCapture, Z as IdentityDocumentSpec, _ as IdentityFieldRule, $ as IdentityRulesV1, a0 as IdentityStrategy, a1 as Image, a2 as InsufficientStockDetails, a4 as InvoiceAction, a7 as InvoiceStage, a8 as InvoiceSummary, a9 as InvoicingCapabilities, ab as LocationContacts, ac as LocationKind, ae as LocationPickup, ag as MenuItem, ai as MoneyRange, al as OrderLine, an as PageInfo, ao as PaymentAction, aq as PaymentAttemptStatus, ar as PaymentClient, as as PaymentClientCsp, au as PaymentFlow, av as PaymentMethod, ay as PaymentOption, az as PaymentOptionKey, aA as PaymentPoint, aD as PickupOption, aF as ProductAttributeValue, aG as ProductCategory, aI as ProductOption, aL as PromotionAnnouncement, aN as PromotionTier, aR as RegionFiscalEntry, aS as RegionFiscalId, aT as RegionPaymentMethod, aY as SEO, aZ as Section, a_ as SelectedOption, a$ as ShippingRate, b1 as ShopBranch, b2 as ShopContact, b3 as ShopPolicies, b5 as StorefrontErrorBody } from './types-C_rsJRCl.js';
 
 type QueryValue = string | number | boolean | null | undefined;
 type QueryParams = Record<string, QueryValue | QueryValue[]>;
@@ -353,6 +353,16 @@ type StorefrontErrorInit = {
     cause?: unknown;
     /** Scopes named by the gateway on a `403 insufficient_scope`. */
     requiredScopes?: string[];
+    /** `error.retryable` as OPS declared it (payment failures). `undefined` = OPS did not say. */
+    retryable?: boolean;
+    /** `error.retry_after` in seconds. */
+    retryAfter?: number;
+    /** `error.checkout_id`: the checkout a refused cart write can resume. */
+    checkoutId?: string;
+    /** `error.cost` of a `price_mismatch` (the cart's current cost; untrusted shape). */
+    cost?: unknown;
+    /** `error.message_en`. */
+    messageEn?: string;
 };
 /**
  * Error thrown by the client for any non-2xx response, network failure,
@@ -367,6 +377,16 @@ declare class StorefrontError extends Error {
     readonly url: string | undefined;
     /** Scopes a `403 insufficient_scope` says the route needs (empty for any other error). */
     readonly requiredScopes: string[];
+    /** `true`: repeating the request (same idempotency key) can succeed. `false`: not until someone fixes something. `undefined`: OPS did not say. */
+    readonly retryable: boolean | undefined;
+    /** Seconds OPS asks to wait before retrying. */
+    readonly retryAfter: number | undefined;
+    /** Checkout that a refused cart write can resume. */
+    readonly checkoutId: string | undefined;
+    /** Current cart cost sent with a `price_mismatch` (untrusted shape). */
+    readonly cost: unknown;
+    /** English version of `message`, when OPS sent one. */
+    readonly messageEn: string | undefined;
     constructor(init: StorefrontErrorInit);
     /**
      * Affected lines of a `409 insufficient_stock` (empty for any other error or a
@@ -375,6 +395,9 @@ declare class StorefrontError extends Error {
      */
     get stockLines(): InsufficientStockLine[];
     toJSON(): {
+        checkoutId?: string | undefined;
+        retryAfter?: number | undefined;
+        retryable?: boolean | undefined;
         requiredScopes?: string[] | undefined;
         name: string;
         status: number;
@@ -385,6 +408,52 @@ declare class StorefrontError extends Error {
 }
 declare function isStorefrontError(err: unknown): err is StorefrontError;
 
+/**
+ * Classification of the failures of a card payment (`POST pay` / `GET status`). No texts, no DOM, no server APIs: the
+ * shop's server uses it to answer with `kind` and `retryable`, and the browser transport uses it to decide whether to
+ * repeat, ask for the status or give up.
+ *
+ * Rule that never changes: an INDETERMINATE result (`transient`, `in_progress`) is never charged again with another
+ * idempotency key; it is repeated with the SAME key or its status is read.
+ */
+type PaymentErrorClassKind = 
+/** OPS or the provider did not answer (5xx, timeout, network). The charge may or may not have happened. */
+'transient'
+/** A payment is already in progress for this order (409): read the status, do not charge again. */
+ | 'in_progress'
+/** Too many attempts (429). */
+ | 'rate_limited'
+/** Credentials or configuration of the merchant with the provider: not the buyer's fault. */
+ | 'merchant_config'
+/** The provider refused the charge at API level (`payment_provider_rejected`): definitive, nothing was charged. */
+ | 'provider_declined'
+/** The cart already became an order and OPS will not open a new attempt (`422 invalid_state`). */
+ | 'stale_checkout' | 'expired' | 'price_mismatch' | 'store_closed' | 'validation' | 'other';
+type PaymentErrorClass = {
+    kind: PaymentErrorClassKind;
+    retryable: boolean;
+};
+type PaymentErrorLike = {
+    status?: number | null;
+    code?: string | null;
+    field?: string | null;
+    /** `error.retryable` as OPS declared it (`StorefrontError.retryable`). */
+    retryable?: boolean | null;
+    /** `error.checkout_id` (`StorefrontError.checkoutId`). */
+    checkoutId?: string | null;
+    /** Raw `error.details`; a `retryable` inside is honoured too (older bodies). */
+    details?: unknown;
+};
+/** Did OPS expressly say the failure must NOT be repeated (`retryable: false`, on the error or inside `details`)? */
+declare function opsSaysNotRetryable(err: PaymentErrorLike): boolean;
+/** Field the shop's server sets when IT refuses a payment row that is not offered (so it is not read as a stale checkout). */
+declare const PAYMENT_CHOICE_REFUSED_FIELD = "payment_choice";
+/**
+ * What a payment failure means and whether repeating it can help. What OPS declares (`retryable`, stable codes) wins
+ * over the HTTP status: a 502 with a stable code is an answer, not "no response".
+ */
+declare function classifyPaymentError(err: PaymentErrorLike): PaymentErrorClass;
+
 /** `sk_…a91f`: the prefix and the last four characters, never enough to use the token. */
 declare function maskToken(token: string | null | undefined): string;
 type DiagnoseOptions = {
@@ -748,4 +817,4 @@ type DeliveryNotices = {
 /** Splits `delivery.unavailable` into the `missing_weight` notice and the generic one. */
 declare function deliveryNotices(delivery: Pick<DeliveryOptions, 'unavailable' | 'partial'> | null | undefined): DeliveryNotices;
 
-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, CustomerCapabilities, CustomerIdentifier, CustomerPasswordLoginInput, CustomerRegisterInput, CustomerRegisterResult, CustomerResetPasswordInput, CustomerSession, CustomerSessionInput, CustomerSetPasswordInput, CustomerUpdateInput, CustomerVerifyRegistrationInput, DeclineCode, type DeliveryChoice, type DeliveryChoiceKind, DeliveryInput, DeliveryMethod, type DeliveryNotices, DeliveryOptions, type DiagnoseOptions, type DiscountBarState, type DiscountBarView, type FetchLike, type FormatMoneyOptions, GeoPoint, InsufficientStockLine, InvoiceRequest, InvoiceResult, Location, LocationListParams, MISSING_WEIGHT, 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, Region, 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, TokenIntrospection, UnavailableRateProvider, type WriteOptions, appendParams, availabilityLocale, availabilityMessages, availabilityView, cartLineProblemView, clampPercent, createStorefrontClient, declineMessage, declineMessageKey, deliveryInput, deliveryNotices, diagnose, formatAvailabilityMessage, formatMoney, formatVoucherExpiry, generateIdempotencyKey, hreflangLinks, isStorefrontError, isTokenPublishable, maskToken, negotiateLocale, normalizeClientIp, normalizeNote, parseDelivery, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, preferredLanguages, productAvailability, productListQuery, promoProgressView, promotionMessages, repairPath, resolveAvailability, rewardLabel, safeHttpsUrl, schemaAvailability, storefrontDomainHeader, suggestMarket, toMoney, visitorCountry };
+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, CustomerCapabilities, CustomerIdentifier, CustomerPasswordLoginInput, CustomerRegisterInput, CustomerRegisterResult, CustomerResetPasswordInput, CustomerSession, CustomerSessionInput, CustomerSetPasswordInput, CustomerUpdateInput, CustomerVerifyRegistrationInput, DeclineCode, type DeliveryChoice, type DeliveryChoiceKind, DeliveryInput, DeliveryMethod, type DeliveryNotices, DeliveryOptions, type DiagnoseOptions, type DiscountBarState, type DiscountBarView, type FetchLike, type FormatMoneyOptions, GeoPoint, InsufficientStockLine, InvoiceRequest, InvoiceResult, Location, LocationListParams, MISSING_WEIGHT, type MarketInfo, type MarketSuggestion, Menu, Money, NOTE_MAX_LENGTH, NearestLocation, Order, PAYMENT_CHOICE_REFUSED_FIELD, Page, type PaginationParams, PaymentAttemptResult, PaymentConfig, type PaymentErrorClass, type PaymentErrorClassKind, type PaymentErrorKind, type PaymentErrorLike, 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, Region, 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, TokenIntrospection, UnavailableRateProvider, type WriteOptions, appendParams, availabilityLocale, availabilityMessages, availabilityView, cartLineProblemView, clampPercent, classifyPaymentError, createStorefrontClient, declineMessage, declineMessageKey, deliveryInput, deliveryNotices, diagnose, formatAvailabilityMessage, formatMoney, formatVoucherExpiry, generateIdempotencyKey, hreflangLinks, isStorefrontError, isTokenPublishable, maskToken, negotiateLocale, normalizeClientIp, normalizeNote, opsSaysNotRetryable, parseDelivery, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, preferredLanguages, productAvailability, productListQuery, promoProgressView, promotionMessages, repairPath, resolveAvailability, rewardLabel, safeHttpsUrl, schemaAvailability, storefrontDomainHeader, suggestMarket, toMoney, visitorCountry };

package/dist/index.js

@@ -12,6 +12,16 @@ var StorefrontError = class extends Error {
   url;
   /** Scopes a `403 insufficient_scope` says the route needs (empty for any other error). */
   requiredScopes;
+  /** `true`: repeating the request (same idempotency key) can succeed. `false`: not until someone fixes something. `undefined`: OPS did not say. */
+  retryable;
+  /** Seconds OPS asks to wait before retrying. */
+  retryAfter;
+  /** Checkout that a refused cart write can resume. */
+  checkoutId;
+  /** Current cart cost sent with a `price_mismatch` (untrusted shape). */
+  cost;
+  /** English version of `message`, when OPS sent one. */
+  messageEn;
   constructor(init) {
     super(init.message, init.cause === void 0 ? void 0 : { cause: init.cause });
     this.status = init.status;
@@ -20,6 +30,11 @@ var StorefrontError = class extends Error {
     this.details = init.details;
     this.url = init.url;
     this.requiredScopes = init.requiredScopes ?? [];
+    this.retryable = init.retryable;
+    this.retryAfter = init.retryAfter;
+    this.checkoutId = init.checkoutId;
+    this.cost = init.cost;
+    this.messageEn = init.messageEn;
   }
   /**
    * Affected lines of a `409 insufficient_stock` (empty for any other error or a
@@ -38,7 +53,10 @@ var StorefrontError = class extends Error {
       code: this.code,
       message: this.message,
       field: this.field,
-      ...this.requiredScopes.length ? { requiredScopes: this.requiredScopes } : {}
+      ...this.requiredScopes.length ? { requiredScopes: this.requiredScopes } : {},
+      ...this.retryable !== void 0 ? { retryable: this.retryable } : {},
+      ...this.retryAfter !== void 0 ? { retryAfter: this.retryAfter } : {},
+      ...this.checkoutId ? { checkoutId: this.checkoutId } : {}
     };
   }
 };
@@ -199,6 +217,11 @@ async function readError(res, url) {
     message: e?.message ?? `Storefront API responded ${res.status}${res.statusText ? " " + res.statusText : ""}`,
     ...e?.field ? { field: e.field } : {},
     ...e?.details !== void 0 ? { details: e.details } : {},
+    ...typeof e?.retryable === "boolean" ? { retryable: e.retryable } : {},
+    ...typeof e?.retry_after === "number" && e.retry_after > 0 ? { retryAfter: e.retry_after } : {},
+    ...typeof e?.checkout_id === "string" && e.checkout_id ? { checkoutId: e.checkout_id } : {},
+    ...e?.cost !== void 0 ? { cost: e.cost } : {},
+    ...typeof e?.message_en === "string" && e.message_en ? { messageEn: e.message_en } : {},
     url
   });
 }
@@ -480,6 +503,35 @@ function storefrontDomainHeader(domain, market) {
   return code && /^[a-z0-9_-]{1,32}$/.test(code) ? `${host}#${code}` : host;
 }
 
+// src/payment-errors.ts
+function opsSaysNotRetryable(err) {
+  if (err.retryable === false) return true;
+  const d = err.details;
+  return typeof d === "object" && d !== null && d.retryable === false;
+}
+var PAYMENT_CHOICE_REFUSED_FIELD = "payment_choice";
+var MERCHANT_CONFIG_CODE = /credential|not_configured|unconfigured|invalid_access|access_token|provider_config|merchant|invalid_public_key|unauthorized/i;
+function classifyPaymentError(err) {
+  const status = typeof err.status === "number" ? err.status : 0;
+  const code = typeof err.code === "string" ? err.code : "";
+  if (code === "store_not_ready") return { kind: "store_closed", retryable: false };
+  if (code === "price_mismatch" || status === 422 && err.field === "expected_total") return { kind: "price_mismatch", retryable: false };
+  if (status === 409 && (code === "payment_in_progress" || err.field === "payment_in_progress")) return { kind: "in_progress", retryable: true };
+  if (status === 409 && code === "expired") return { kind: "expired", retryable: false };
+  if (status === 429 || code === "too_many_attempts" || code === "rate_limited") return { kind: "rate_limited", retryable: true };
+  if (status === 422 && code === "invalid_state") {
+    if (err.field === PAYMENT_CHOICE_REFUSED_FIELD) return { kind: "other", retryable: false };
+    return { kind: "stale_checkout", retryable: false };
+  }
+  if (code === "payment_provider_misconfigured") return { kind: "merchant_config", retryable: false };
+  if (code === "payment_provider_rejected") return { kind: "provider_declined", retryable: false };
+  if (MERCHANT_CONFIG_CODE.test(code) || status === 401 || status === 403) return { kind: "merchant_config", retryable: false };
+  if (status >= 500 && opsSaysNotRetryable(err)) return { kind: "other", retryable: false };
+  if (status === 0 || status >= 500 || code === "network" || code === "timeout" || code === "unavailable") return { kind: "transient", retryable: true };
+  if (status === 400 || code === "validation") return { kind: "validation", retryable: false };
+  return { kind: "other", retryable: false };
+}
+
 // src/diagnose.ts
 function maskToken(token) {
   if (!token) return "(sin token)";
@@ -725,7 +777,9 @@ function paymentErrorView(err, locale, overrides) {
   if (status === 429 || code === "too_many_attempts") {
     return { kind: "too_many_attempts", message: m["error.too_many_attempts"], retrySameAttempt: false, canRetry: false };
   }
-  if (status === 0 || status === 502 || status === 503 || status === 504 || code === "network" || code === "timeout") {
+  const declared = e.retryable;
+  if (status >= 500 && declared === false) return { kind: "generic", message: m["error.generic"], retrySameAttempt: false, canRetry: true };
+  if (status === 0 || status === 502 || status === 503 || status === 504 || code === "network" || code === "timeout" || status >= 500) {
     return { kind: "network", message: m["error.network"], retrySameAttempt: true, canRetry: true };
   }
   return { kind: "generic", message: m["error.generic"], retrySameAttempt: false, canRetry: true };
@@ -1024,6 +1078,6 @@ function deliveryNotices(delivery) {
   };
 }
 
-export { CLIENT_IP_HEADER, COUNTRY_HEADERS, MISSING_WEIGHT, NOTE_MAX_LENGTH, StorefrontError, appendParams, clampPercent, createStorefrontClient, declineMessage, declineMessageKey, deliveryInput, deliveryNotices, diagnose, formatMoney, formatVoucherExpiry, generateIdempotencyKey, hreflangLinks, isStorefrontError, isTokenPublishable, maskToken, negotiateLocale, normalizeClientIp, normalizeNote, parseDelivery, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, preferredLanguages, productListQuery, promoProgressView, promotionMessages, repairPath, rewardLabel, safeHttpsUrl, storefrontDomainHeader, suggestMarket, toMoney, visitorCountry };
+export { CLIENT_IP_HEADER, COUNTRY_HEADERS, MISSING_WEIGHT, NOTE_MAX_LENGTH, PAYMENT_CHOICE_REFUSED_FIELD, StorefrontError, appendParams, clampPercent, classifyPaymentError, createStorefrontClient, declineMessage, declineMessageKey, deliveryInput, deliveryNotices, diagnose, formatMoney, formatVoucherExpiry, generateIdempotencyKey, hreflangLinks, isStorefrontError, isTokenPublishable, maskToken, negotiateLocale, normalizeClientIp, normalizeNote, opsSaysNotRetryable, parseDelivery, parseMoney, parseProductFilters, paymentErrorView, paymentIdempotencyKey, paymentMessages, paymentOutcome, preferredLanguages, productListQuery, promoProgressView, promotionMessages, repairPath, rewardLabel, safeHttpsUrl, storefrontDomainHeader, suggestMarket, toMoney, visitorCountry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map