@bacano/sdk 1.2.7 → 1.2.9

package/react.cjs

@@ -5930,6 +5930,78 @@ function hasRecoverableCartSessionError(errors) {
   );
 }
 
+// libs/sdk/src/modules/checkout-contact.ts
+var EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var PHONE_PATTERN = /^\+?\d{7,15}$/;
+function validEmail(value) {
+  if (value.length > 320 || !EMAIL_PATTERN.test(value)) return false;
+  const [local, domain] = value.split("@");
+  if (!local || !domain || local.length > 64 || domain.length > 255 || local.startsWith(".") || local.endsWith(".") || local.includes("..")) {
+    return false;
+  }
+  return domain.split(".").every((label) => /^[a-z\d](?:[a-z\d-]*[a-z\d])?$/i.test(label));
+}
+function normalizePhone(value) {
+  return value.trim().replace(/[\s().-]/g, "");
+}
+function invalidContact(field) {
+  const messages = {
+    email: "Revisa el correo electr\xF3nico: debe estar completo y sin espacios.",
+    phone: "Revisa el n\xFAmero de tel\xE9fono: usa entre 7 y 15 d\xEDgitos.",
+    contact: "Ingresa un correo electr\xF3nico o un n\xFAmero de tel\xE9fono v\xE1lido."
+  };
+  return new WebsiteError(
+    messages[field],
+    `INVALID_CHECKOUT_${field.toUpperCase()}`
+  );
+}
+function normalizeCheckoutContact(contact, mode) {
+  const email = contact.email?.trim() || void 0;
+  const phone = contact.phone ? normalizePhone(contact.phone) : void 0;
+  const cellphone = contact.cellphone ? normalizePhone(contact.cellphone) : void 0;
+  const emailValid = !email || validEmail(email);
+  const phoneValid = !phone || PHONE_PATTERN.test(phone);
+  const cellphoneValid = !cellphone || PHONE_PATTERN.test(cellphone);
+  if (mode === "submit") {
+    if (!emailValid) throw invalidContact("email");
+    if (!phoneValid || !cellphoneValid) throw invalidContact("phone");
+  }
+  const normalized = {
+    ...contact,
+    name: contact.name?.trim() || void 0,
+    firstName: contact.firstName?.trim() || void 0,
+    lastName: contact.lastName?.trim() || void 0,
+    email: emailValid ? email : void 0,
+    phone: phoneValid ? phone : void 0,
+    cellphone: cellphoneValid ? cellphone : void 0
+  };
+  if ((normalized.name?.length ?? 0) > 160 || (normalized.firstName?.length ?? 0) > 80 || (normalized.lastName?.length ?? 0) > 80) {
+    throw new WebsiteError(
+      "Revisa los datos de contacto: el nombre es demasiado largo.",
+      "INVALID_CHECKOUT_CONTACT"
+    );
+  }
+  if (!normalized.email && !normalized.phone && !normalized.cellphone) {
+    throw invalidContact(
+      !emailValid ? "email" : !phoneValid || !cellphoneValid ? "phone" : "contact"
+    );
+  }
+  return normalized;
+}
+function explainCheckoutRequestError(error) {
+  if (error instanceof GraphQLRequestError && error.graphqlErrors.some(
+    (item) => /invalid request payload|hay un error en los datos del pedido/i.test(
+      item.message
+    )
+  )) {
+    throw new WebsiteError(
+      "Hay un error en los datos del pedido. Rev\xEDsalos e intenta de nuevo.",
+      "INVALID_CHECKOUT_DATA"
+    );
+  }
+  throw error;
+}
+
 // libs/sdk/src/modules/cart.ts
 function mapCartItem(raw) {
   return {
@@ -6005,6 +6077,15 @@ function requireCartSession(storage) {
   return session;
 }
 function createCartModule(graphqlUrl, getHeaders, getContext, cartSessionStorage) {
+  let pendingCartSessionOperation = Promise.resolve();
+  function enqueueCartSessionOperation(run) {
+    const operation = pendingCartSessionOperation.then(run, run);
+    pendingCartSessionOperation = operation.then(
+      () => void 0,
+      () => void 0
+    );
+    return operation;
+  }
   async function fetchCart(orderId, cartToken) {
     const data = await executeGraphQL(graphqlUrl, GET_CART, { orderId, cartToken }, getHeaders);
     const result = data.websiteGetCart;
@@ -6027,72 +6108,80 @@ function createCartModule(graphqlUrl, getHeaders, getContext, cartSessionStorage
   }
   return {
     async getOrCreate(contact, fulfillmentFamily) {
-      const ctx = getContext();
-      if (!ctx.chainId) {
-        throw new WebsiteError(
-          "This website has no chain configured. Cart requires a chain_id.",
-          "NO_CHAIN"
-        );
-      }
-      const existing = cartSessionStorage.get();
-      const data = await executeGraphQL(
-        graphqlUrl,
-        CREATE_CART,
-        {
-          websiteId: ctx.websiteId,
-          cartToken: existing?.cartToken,
-          contact,
-          fulfillmentFamily
-        },
-        getHeaders
-      );
-      const result = data.websiteCreateCart;
-      assertActionSuccess(result, "CART_CREATE_ERROR");
-      cartSessionStorage.set({
-        orderId: result.order_id,
-        cartToken: result.cart_token
-      });
-      return mapCart(result.cart, result.cart_token);
-    },
-    async startCheckout(input) {
-      const ctx = getContext();
-      if (!ctx.chainId) {
-        throw new WebsiteError(
-          "This website has no chain configured. Checkout requires a chain_id.",
-          "NO_CHAIN"
-        );
-      }
-      const requestStartCheckout = async (cartToken) => {
+      return enqueueCartSessionOperation(async () => {
+        const normalizedContact = contact ? normalizeCheckoutContact(contact, "draft") : void 0;
+        const ctx = getContext();
+        if (!ctx.chainId) {
+          throw new WebsiteError(
+            "This website has no chain configured. Cart requires a chain_id.",
+            "NO_CHAIN"
+          );
+        }
+        const existing = cartSessionStorage.get();
         const data = await executeGraphQL(
           graphqlUrl,
-          START_GUEST_CHECKOUT,
+          CREATE_CART,
           {
             websiteId: ctx.websiteId,
-            cartToken,
-            contact: input.contact,
-            fulfillmentFamily: input.fulfillmentFamily,
-            items: input.items.map((item) => ({
-              product_variant_id: item.productVariantId,
-              quantity: item.quantity
-            })),
-            marketingAttribution: input.marketingAttribution ? serializeWebsiteMarketingAttribution(input.marketingAttribution) : void 0
+            cartToken: existing?.cartToken,
+            contact: normalizedContact,
+            fulfillmentFamily
           },
           getHeaders
-        );
-        return data.websiteStartGuestCheckout;
-      };
-      const existing = cartSessionStorage.get();
-      let result = await requestStartCheckout(existing?.cartToken);
-      if (existing && !result.success && hasRecoverableCartSessionError(result.errors)) {
-        cartSessionStorage.clear();
-        result = await requestStartCheckout();
-      }
-      assertActionSuccess(result, "CHECKOUT_START_ERROR");
-      cartSessionStorage.set({
-        orderId: result.order_id,
-        cartToken: result.cart_token
+        ).catch(explainCheckoutRequestError);
+        const result = data.websiteCreateCart;
+        assertActionSuccess(result, "CART_CREATE_ERROR");
+        cartSessionStorage.set({
+          orderId: result.order_id,
+          cartToken: result.cart_token
+        });
+        return mapCart(result.cart, result.cart_token);
+      });
+    },
+    async startCheckout(input) {
+      return enqueueCartSessionOperation(async () => {
+        const contact = normalizeCheckoutContact(input.contact, "draft");
+        const ctx = getContext();
+        if (!ctx.chainId) {
+          throw new WebsiteError(
+            "This website has no chain configured. Checkout requires a chain_id.",
+            "NO_CHAIN"
+          );
+        }
+        const requestStartCheckout = async (cartToken) => {
+          const data = await executeGraphQL(
+            graphqlUrl,
+            START_GUEST_CHECKOUT,
+            {
+              websiteId: ctx.websiteId,
+              cartToken,
+              contact,
+              fulfillmentFamily: input.fulfillmentFamily,
+              items: input.items.map((item) => ({
+                product_variant_id: item.productVariantId,
+                quantity: item.quantity
+              })),
+              marketingAttribution: input.marketingAttribution ? serializeWebsiteMarketingAttribution(
+                input.marketingAttribution
+              ) : void 0
+            },
+            getHeaders
+          ).catch(explainCheckoutRequestError);
+          return data.websiteStartGuestCheckout;
+        };
+        const existing = cartSessionStorage.get();
+        let result = await requestStartCheckout(existing?.cartToken);
+        if (existing && !result.success && hasRecoverableCartSessionError(result.errors)) {
+          cartSessionStorage.clear();
+          result = await requestStartCheckout();
+        }
+        assertActionSuccess(result, "CHECKOUT_START_ERROR");
+        cartSessionStorage.set({
+          orderId: result.order_id,
+          cartToken: result.cart_token
+        });
+        return mapCart(result.cart, result.cart_token);
       });
-      return mapCart(result.cart, result.cart_token);
     },
     async get() {
       const session = cartSessionStorage.get();
@@ -6631,6 +6720,7 @@ function createCheckoutModule(graphqlUrl, getHeaders, getContext, cartSessionSto
       return mapCouponResult(data.websiteRemoveCoupon);
     },
     async submit(input) {
+      const contact = normalizeCheckoutContact(input.contact, "submit");
       const session = requireCartSession2(cartSessionStorage);
       const data = await executeGraphQL(
         graphqlUrl,
@@ -6638,7 +6728,7 @@ function createCheckoutModule(graphqlUrl, getHeaders, getContext, cartSessionSto
         {
           orderId: session.orderId,
           cartToken: session.cartToken,
-          contact: input.contact,
+          contact,
           fulfillmentFamily: input.fulfillmentFamily,
           address: input.address,
           shippingQuoteId: input.shippingQuoteId,
@@ -6658,7 +6748,7 @@ function createCheckoutModule(graphqlUrl, getHeaders, getContext, cartSessionSto
           } : void 0
         },
         getHeaders
-      );
+      ).catch(explainCheckoutRequestError);
       const result = data.websiteCheckout;
       if (!result.success && result.errors && result.errors.length > 0) {
         throw new CheckoutError(result.errors);
@@ -6699,7 +6789,7 @@ function createCheckoutModule(graphqlUrl, getHeaders, getContext, cartSessionSto
           returnUrl: input.returnUrl
         },
         getHeaders
-      );
+      ).catch(explainCheckoutRequestError);
       const result = data.websiteCreatePaymentSession;
       if (result.success && result.payment_session_id && (result.integration_mode !== "redirect" || !result.redirect_url)) {
         throw new WebsiteError(
@@ -6734,7 +6824,7 @@ function createCheckoutModule(graphqlUrl, getHeaders, getContext, cartSessionSto
           gatewayTransactionId: input.gatewayTransactionId
         },
         getHeaders
-      );
+      ).catch(explainCheckoutRequestError);
       const result = data.websiteReconcilePaymentSession;
       return {
         success: result.success,

package/react.js

@@ -5877,6 +5877,78 @@ function hasRecoverableCartSessionError(errors) {
   );
 }
 
+// libs/sdk/src/modules/checkout-contact.ts
+var EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var PHONE_PATTERN = /^\+?\d{7,15}$/;
+function validEmail(value) {
+  if (value.length > 320 || !EMAIL_PATTERN.test(value)) return false;
+  const [local, domain] = value.split("@");
+  if (!local || !domain || local.length > 64 || domain.length > 255 || local.startsWith(".") || local.endsWith(".") || local.includes("..")) {
+    return false;
+  }
+  return domain.split(".").every((label) => /^[a-z\d](?:[a-z\d-]*[a-z\d])?$/i.test(label));
+}
+function normalizePhone(value) {
+  return value.trim().replace(/[\s().-]/g, "");
+}
+function invalidContact(field) {
+  const messages = {
+    email: "Revisa el correo electr\xF3nico: debe estar completo y sin espacios.",
+    phone: "Revisa el n\xFAmero de tel\xE9fono: usa entre 7 y 15 d\xEDgitos.",
+    contact: "Ingresa un correo electr\xF3nico o un n\xFAmero de tel\xE9fono v\xE1lido."
+  };
+  return new WebsiteError(
+    messages[field],
+    `INVALID_CHECKOUT_${field.toUpperCase()}`
+  );
+}
+function normalizeCheckoutContact(contact, mode) {
+  const email = contact.email?.trim() || void 0;
+  const phone = contact.phone ? normalizePhone(contact.phone) : void 0;
+  const cellphone = contact.cellphone ? normalizePhone(contact.cellphone) : void 0;
+  const emailValid = !email || validEmail(email);
+  const phoneValid = !phone || PHONE_PATTERN.test(phone);
+  const cellphoneValid = !cellphone || PHONE_PATTERN.test(cellphone);
+  if (mode === "submit") {
+    if (!emailValid) throw invalidContact("email");
+    if (!phoneValid || !cellphoneValid) throw invalidContact("phone");
+  }
+  const normalized = {
+    ...contact,
+    name: contact.name?.trim() || void 0,
+    firstName: contact.firstName?.trim() || void 0,
+    lastName: contact.lastName?.trim() || void 0,
+    email: emailValid ? email : void 0,
+    phone: phoneValid ? phone : void 0,
+    cellphone: cellphoneValid ? cellphone : void 0
+  };
+  if ((normalized.name?.length ?? 0) > 160 || (normalized.firstName?.length ?? 0) > 80 || (normalized.lastName?.length ?? 0) > 80) {
+    throw new WebsiteError(
+      "Revisa los datos de contacto: el nombre es demasiado largo.",
+      "INVALID_CHECKOUT_CONTACT"
+    );
+  }
+  if (!normalized.email && !normalized.phone && !normalized.cellphone) {
+    throw invalidContact(
+      !emailValid ? "email" : !phoneValid || !cellphoneValid ? "phone" : "contact"
+    );
+  }
+  return normalized;
+}
+function explainCheckoutRequestError(error) {
+  if (error instanceof GraphQLRequestError && error.graphqlErrors.some(
+    (item) => /invalid request payload|hay un error en los datos del pedido/i.test(
+      item.message
+    )
+  )) {
+    throw new WebsiteError(
+      "Hay un error en los datos del pedido. Rev\xEDsalos e intenta de nuevo.",
+      "INVALID_CHECKOUT_DATA"
+    );
+  }
+  throw error;
+}
+
 // libs/sdk/src/modules/cart.ts
 function mapCartItem(raw) {
   return {
@@ -5952,6 +6024,15 @@ function requireCartSession(storage) {
   return session;
 }
 function createCartModule(graphqlUrl, getHeaders, getContext, cartSessionStorage) {
+  let pendingCartSessionOperation = Promise.resolve();
+  function enqueueCartSessionOperation(run) {
+    const operation = pendingCartSessionOperation.then(run, run);
+    pendingCartSessionOperation = operation.then(
+      () => void 0,
+      () => void 0
+    );
+    return operation;
+  }
   async function fetchCart(orderId, cartToken) {
     const data = await executeGraphQL(graphqlUrl, GET_CART, { orderId, cartToken }, getHeaders);
     const result = data.websiteGetCart;
@@ -5974,72 +6055,80 @@ function createCartModule(graphqlUrl, getHeaders, getContext, cartSessionStorage
   }
   return {
     async getOrCreate(contact, fulfillmentFamily) {
-      const ctx = getContext();
-      if (!ctx.chainId) {
-        throw new WebsiteError(
-          "This website has no chain configured. Cart requires a chain_id.",
-          "NO_CHAIN"
-        );
-      }
-      const existing = cartSessionStorage.get();
-      const data = await executeGraphQL(
-        graphqlUrl,
-        CREATE_CART,
-        {
-          websiteId: ctx.websiteId,
-          cartToken: existing?.cartToken,
-          contact,
-          fulfillmentFamily
-        },
-        getHeaders
-      );
-      const result = data.websiteCreateCart;
-      assertActionSuccess(result, "CART_CREATE_ERROR");
-      cartSessionStorage.set({
-        orderId: result.order_id,
-        cartToken: result.cart_token
-      });
-      return mapCart(result.cart, result.cart_token);
-    },
-    async startCheckout(input) {
-      const ctx = getContext();
-      if (!ctx.chainId) {
-        throw new WebsiteError(
-          "This website has no chain configured. Checkout requires a chain_id.",
-          "NO_CHAIN"
-        );
-      }
-      const requestStartCheckout = async (cartToken) => {
+      return enqueueCartSessionOperation(async () => {
+        const normalizedContact = contact ? normalizeCheckoutContact(contact, "draft") : void 0;
+        const ctx = getContext();
+        if (!ctx.chainId) {
+          throw new WebsiteError(
+            "This website has no chain configured. Cart requires a chain_id.",
+            "NO_CHAIN"
+          );
+        }
+        const existing = cartSessionStorage.get();
         const data = await executeGraphQL(
           graphqlUrl,
-          START_GUEST_CHECKOUT,
+          CREATE_CART,
           {
             websiteId: ctx.websiteId,
-            cartToken,
-            contact: input.contact,
-            fulfillmentFamily: input.fulfillmentFamily,
-            items: input.items.map((item) => ({
-              product_variant_id: item.productVariantId,
-              quantity: item.quantity
-            })),
-            marketingAttribution: input.marketingAttribution ? serializeWebsiteMarketingAttribution(input.marketingAttribution) : void 0
+            cartToken: existing?.cartToken,
+            contact: normalizedContact,
+            fulfillmentFamily
           },
           getHeaders
-        );
-        return data.websiteStartGuestCheckout;
-      };
-      const existing = cartSessionStorage.get();
-      let result = await requestStartCheckout(existing?.cartToken);
-      if (existing && !result.success && hasRecoverableCartSessionError(result.errors)) {
-        cartSessionStorage.clear();
-        result = await requestStartCheckout();
-      }
-      assertActionSuccess(result, "CHECKOUT_START_ERROR");
-      cartSessionStorage.set({
-        orderId: result.order_id,
-        cartToken: result.cart_token
+        ).catch(explainCheckoutRequestError);
+        const result = data.websiteCreateCart;
+        assertActionSuccess(result, "CART_CREATE_ERROR");
+        cartSessionStorage.set({
+          orderId: result.order_id,
+          cartToken: result.cart_token
+        });
+        return mapCart(result.cart, result.cart_token);
+      });
+    },
+    async startCheckout(input) {
+      return enqueueCartSessionOperation(async () => {
+        const contact = normalizeCheckoutContact(input.contact, "draft");
+        const ctx = getContext();
+        if (!ctx.chainId) {
+          throw new WebsiteError(
+            "This website has no chain configured. Checkout requires a chain_id.",
+            "NO_CHAIN"
+          );
+        }
+        const requestStartCheckout = async (cartToken) => {
+          const data = await executeGraphQL(
+            graphqlUrl,
+            START_GUEST_CHECKOUT,
+            {
+              websiteId: ctx.websiteId,
+              cartToken,
+              contact,
+              fulfillmentFamily: input.fulfillmentFamily,
+              items: input.items.map((item) => ({
+                product_variant_id: item.productVariantId,
+                quantity: item.quantity
+              })),
+              marketingAttribution: input.marketingAttribution ? serializeWebsiteMarketingAttribution(
+                input.marketingAttribution
+              ) : void 0
+            },
+            getHeaders
+          ).catch(explainCheckoutRequestError);
+          return data.websiteStartGuestCheckout;
+        };
+        const existing = cartSessionStorage.get();
+        let result = await requestStartCheckout(existing?.cartToken);
+        if (existing && !result.success && hasRecoverableCartSessionError(result.errors)) {
+          cartSessionStorage.clear();
+          result = await requestStartCheckout();
+        }
+        assertActionSuccess(result, "CHECKOUT_START_ERROR");
+        cartSessionStorage.set({
+          orderId: result.order_id,
+          cartToken: result.cart_token
+        });
+        return mapCart(result.cart, result.cart_token);
       });
-      return mapCart(result.cart, result.cart_token);
     },
     async get() {
       const session = cartSessionStorage.get();
@@ -6578,6 +6667,7 @@ function createCheckoutModule(graphqlUrl, getHeaders, getContext, cartSessionSto
       return mapCouponResult(data.websiteRemoveCoupon);
     },
     async submit(input) {
+      const contact = normalizeCheckoutContact(input.contact, "submit");
       const session = requireCartSession2(cartSessionStorage);
       const data = await executeGraphQL(
         graphqlUrl,
@@ -6585,7 +6675,7 @@ function createCheckoutModule(graphqlUrl, getHeaders, getContext, cartSessionSto
         {
           orderId: session.orderId,
           cartToken: session.cartToken,
-          contact: input.contact,
+          contact,
           fulfillmentFamily: input.fulfillmentFamily,
           address: input.address,
           shippingQuoteId: input.shippingQuoteId,
@@ -6605,7 +6695,7 @@ function createCheckoutModule(graphqlUrl, getHeaders, getContext, cartSessionSto
           } : void 0
         },
         getHeaders
-      );
+      ).catch(explainCheckoutRequestError);
       const result = data.websiteCheckout;
       if (!result.success && result.errors && result.errors.length > 0) {
         throw new CheckoutError(result.errors);
@@ -6646,7 +6736,7 @@ function createCheckoutModule(graphqlUrl, getHeaders, getContext, cartSessionSto
           returnUrl: input.returnUrl
         },
         getHeaders
-      );
+      ).catch(explainCheckoutRequestError);
       const result = data.websiteCreatePaymentSession;
       if (result.success && result.payment_session_id && (result.integration_mode !== "redirect" || !result.redirect_url)) {
         throw new WebsiteError(
@@ -6681,7 +6771,7 @@ function createCheckoutModule(graphqlUrl, getHeaders, getContext, cartSessionSto
           gatewayTransactionId: input.gatewayTransactionId
         },
         getHeaders
-      );
+      ).catch(explainCheckoutRequestError);
       const result = data.websiteReconcilePaymentSession;
       return {
         success: result.success,

package/skills/bacano-web/SKILL.md

@@ -54,9 +54,16 @@ otros contratos únicamente cuando esas capacidades existan. Leer
 `STOREFRONT_CONSTRUCTION.md` cuando el website permita ocultarse temporalmente.
 Si la tienda acepta pagos, leer obligatoriamente `STOREFRONT_PAYMENTS.md` antes
 de implementar, depurar o auditar checkout, retorno, reintentos o webhooks.
-Si existen formularios administrados desde Bacano, leer obligatoriamente
-`STOREFRONT_FORMS.md` y
-[references/forms.md](references/forms.md) antes de auditarlos o modificarlos.
+En un checkout con autoguardado, comprobar además que no cree pedidos con
+contactos parciales ni solicitudes simultáneas; tras un rechazo, el reintento
+debe conservar el mismo pedido incluso si la sesión de pasarela sigue
+`pending`. Aplicar los casos de [references/storefront.md](references/storefront.md).
+Si existe cualquier formulario visible, leer obligatoriamente
+`STOREFRONT_FORMS.md`. Para formularios propios del storefront, comprobar que
+Zod valida el flujo real, con pruebas de errores por campo y bloqueo del envío
+inválido; su mera presencia en `package.json` no basta. Si el formulario es
+administrado desde Bacano, leer además [references/forms.md](references/forms.md)
+y no duplicar su definición publicada en Zod.
 Cuando marketing esté activo y existan CTA o formularios, leer
 [references/interactions.md](references/interactions.md): inventariar los CTA,
 asignar un propietario por evento y usar los helpers oficiales del SDK. Esta

package/skills/bacano-web/references/common.md

@@ -76,6 +76,11 @@ función apagada en un bloqueo artificial.
 - Navegación por teclado, foco visible, landmarks, labels, contraste y zoom.
 - Formularios con errores específicos, estados de envío y prevención de doble
   envío. No usar solo color para comunicar estado.
+- En formularios propios del storefront, verificar Zod en dependencias **y** en
+  el código que valida antes del envío; comprobar pruebas para valores válidos,
+  inválidos y corrección del error. Si falta, registrar `P1 · Calidad`; si un
+  dato inválido llega a checkout o impide comprar, evaluar además el flujo como
+  `P0 · Gate`. No exigir un esquema Zod paralelo a `BacanoForm`.
 - Probar anchos móviles, tablet y escritorio sin scroll interno accidental.
 
 ## Legal y privacidad

package/skills/bacano-web/references/forms.md

@@ -25,6 +25,8 @@ ya resuelve la identidad; no ejecutar una segunda captura por campaña.
 - Reutilizar el único `BacanoProvider` y cliente global del sitio. No crear otro
   cliente, consultar GraphQL ni llamar endpoints internos.
 - No duplicar keys, validaciones, opciones o estructura en un esquema local.
+  En particular, no imponer un esquema Zod paralelo a la definición publicada;
+  Zod corresponde a formularios propios del storefront (ver `STOREFRONT_FORMS.md`).
 - En Static First, obtener la definición durante build/servidor y entregarla
   como `initialForm`. La revalidación runtime no debe borrar el HTML inicial.
 - Renderizar campos directos, secciones visuales y pasos según su semántica. Una

package/skills/bacano-web/references/storefront.md

@@ -56,8 +56,18 @@ Aplicar además de los controles comunes.
 ## Carrito y checkout
 
 - Carrito invitado persiste y sincroniza sin duplicar líneas.
+- Los campos propios de checkout se validan con Zod antes de llamar al SDK.
+  Inspeccionar el esquema, el punto de envío y pruebas de errores por campo:
+  tener Zod instalado o usar solo `type="email"`/`required` no basta. El SDK y
+  Bacano mantienen la validación autoritativa; la web no inventa reglas de pago.
 - Si una operación bloquea temporalmente otras mutaciones del carrito, mostrar
   el indicador de carga en el producto accionado, no en todas las tarjetas.
+- Si hay autoguardado, no crear un pedido con datos de contacto parciales.
+  Validar los campos requeridos por ese checkout y probar escritura rápida del
+  teléfono/correo: una intención de compra mantiene un `orderId` estable.
+- Serializar los inicios de checkout que pueden solaparse (autoguardado, cupón,
+  envío y botón final). Confirmar en un trace que el segundo usa el token
+  entregado por el primero; no asumir que un debounce evita todas las carreras.
 - Probar alta, baja, cambios de cantidad, límites de stock, cupón, envío gratis,
   impuestos, moneda y redondeo.
 - Probar solo los modos activos entre COUNTER, PICKUP y SHIPPING; propia y
@@ -78,6 +88,11 @@ Aplicar además de los controles comunes.
   de riesgo.
 - La página de respuesta no emite `purchase`; Bacano lo hace desde hechos
   autoritativos. Repetir webhook/conciliación no duplica conversiones.
+- Después de abrir la pasarela, comprobar que el storefront conserva el enlace
+  al pedido pero no un carrito local que cree otro pedido al volver. Ante un
+  rechazo con sesión todavía `pending`, la respuesta debe ofrecer
+  `RETRY_PAYMENT` en el mismo pedido; nunca inferir aprobación o rechazo solo
+  del retorno del navegador.
 - Pedido, pago, entrega y desembolso permanecen conceptos separados.
 - Probar consulta pública segura y cuenta autenticada sin filtrar pedidos de
   otra persona, website o canal.