@asteby/storefront 0.11.1 → 0.12.0

package/README.md

@@ -263,6 +263,9 @@ const result = await sf.checkouts.pay(checkout.checkout.id, { method: 'card', pr
   { idempotencyKey: paymentIdempotencyKey(checkout.checkout.id, attemptId) })   // idempotencyKey is REQUIRED (throws before calling)
 const outcome = paymentOutcome(result, 'es-MX')                   // approved | in_review | voucher | challenge | redirect | rejected | expired | cancelled
 paymentErrorView(error)                                           // network (retry same attempt) | price_mismatch | payment_in_progress | expired | too_many_attempts
+classifyPaymentError(error)                                       // { kind, retryable } WITHOUT texts; same rules in the server and the browser
+// kinds: transient | in_progress | rate_limited | merchant_config | provider_declined | stale_checkout | expired | price_mismatch | store_closed | validation | other
+// honours OPS `retryable:false` and the stable codes payment_provider_rejected / payment_provider_misconfigured / unavailable / invalid_state
 ```
 
 - `declineMessage(code, locale)` / `paymentMessages(locale, overrides)`: actionable es/en texts; unknown codes become `declined`.
@@ -443,6 +446,8 @@ connectStore().keepFresh()                // heartbeat; rotates (POST /api/conne
 missing and where to repair them (`OPS → Conexiones y API → <conexión> → Reparar permisos`), showing `sk_…a91f` and never
 the key. Repairing permissions does not change the key.
 
+`StorefrontError` also keeps what OPS sends in `error.*`: `retryable`, `retryAfter`, `checkoutId`, `cost` (of a `price_mismatch`) and `messageEn`.
+
 Errors: a `403 insufficient_scope` is a `StorefrontError` with `code: 'insufficient_scope'`, `status: 403` and
 `requiredScopes: ['customer:write']`. `customer.capabilities()` reports `password: false`, `unavailable_reason:
 'missing_scope'` and `missing_scopes` when the key cannot create accounts. The mock rehearses all of it with

package/dist/cli.js

@@ -15,6 +15,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;
@@ -23,6 +33,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
@@ -41,7 +56,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 } : {}
     };
   }
 };
@@ -169,6 +187,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
   });
 }
@@ -464,7 +487,7 @@ function repairPath(connectionName) {
 import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync } from "fs";
 import { dirname, join, resolve } from "path";
 import { hostname } from "os";
-var SDK_VERSION = true ? "0.11.1" : "dev";
+var SDK_VERSION = true ? "0.12.0" : "dev";
 function writeFileAtomic(file, content, mode = 384) {
   const dir = dirname(file);
   mkdirSync(dir, { recursive: true });

package/dist/fiscal-document.d.cts

@@ -1,5 +1,5 @@
-import { U as FiscalDocumentSource, aR as RegionFiscalEntry, Z as IdentityDocumentSpec, T as FiscalDocumentEvidence, aS as RegionFiscalId, $ as IdentityRulesV1 } from './types-bsdlAumU.cjs';
-export { Y as IdentityCapture, _ as IdentityFieldRule, a0 as IdentityStrategy } from './types-bsdlAumU.cjs';
+import { U as FiscalDocumentSource, aR as RegionFiscalEntry, Z as IdentityDocumentSpec, T as FiscalDocumentEvidence, aS as RegionFiscalId, $ as IdentityRulesV1 } from './types-BQ3S6VjF.cjs';
+export { Y as IdentityCapture, _ as IdentityFieldRule, a0 as IdentityStrategy } from './types-BQ3S6VjF.cjs';
 import './geo.cjs';
 
 /** A value read from a document: text, or the codes of a catalog (`multiple` fields). */

package/dist/fiscal-document.d.ts

@@ -1,5 +1,5 @@
-import { U as FiscalDocumentSource, aR as RegionFiscalEntry, Z as IdentityDocumentSpec, T as FiscalDocumentEvidence, aS as RegionFiscalId, $ as IdentityRulesV1 } from './types-B1E3GySa.js';
-export { Y as IdentityCapture, _ as IdentityFieldRule, a0 as IdentityStrategy } from './types-B1E3GySa.js';
+import { U as FiscalDocumentSource, aR as RegionFiscalEntry, Z as IdentityDocumentSpec, T as FiscalDocumentEvidence, aS as RegionFiscalId, $ as IdentityRulesV1 } from './types-C_rsJRCl.js';
+export { Y as IdentityCapture, _ as IdentityFieldRule, a0 as IdentityStrategy } from './types-C_rsJRCl.js';
 import './geo.js';
 
 /** A value read from a document: text, or the codes of a catalog (`multiple` fields). */

package/dist/index.cjs

@@ -10,6 +10,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;
@@ -18,6 +28,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
@@ -36,7 +51,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 } : {}
     };
   }
 };
@@ -201,6 +219,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
   });
 }
@@ -482,6 +505,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)";
@@ -944,7 +996,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 };
@@ -1247,6 +1301,7 @@ exports.CLIENT_IP_HEADER = CLIENT_IP_HEADER;
 exports.COUNTRY_HEADERS = COUNTRY_HEADERS;
 exports.MISSING_WEIGHT = MISSING_WEIGHT;
 exports.NOTE_MAX_LENGTH = NOTE_MAX_LENGTH;
+exports.PAYMENT_CHOICE_REFUSED_FIELD = PAYMENT_CHOICE_REFUSED_FIELD;
 exports.StorefrontError = StorefrontError;
 exports.appendParams = appendParams;
 exports.availabilityLocale = availabilityLocale;
@@ -1254,6 +1309,7 @@ exports.availabilityMessages = availabilityMessages;
 exports.availabilityView = availabilityView;
 exports.cartLineProblemView = cartLineProblemView;
 exports.clampPercent = clampPercent;
+exports.classifyPaymentError = classifyPaymentError;
 exports.createStorefrontClient = createStorefrontClient;
 exports.declineMessage = declineMessage;
 exports.declineMessageKey = declineMessageKey;
@@ -1271,6 +1327,7 @@ exports.maskToken = maskToken;
 exports.negotiateLocale = negotiateLocale;
 exports.normalizeClientIp = normalizeClientIp;
 exports.normalizeNote = normalizeNote;
+exports.opsSaysNotRetryable = opsSaysNotRetryable;
 exports.parseDelivery = parseDelivery;
 exports.parseMoney = parseMoney;
 exports.parseProductFilters = parseProductFilters;