@bacano/sdk 1.1.0 → 1.1.9

package/README.md

@@ -66,6 +66,16 @@ in [`STOREFRONT_CONSTRUCTION.md`](./STOREFRONT_CONSTRUCTION.md). It supports
 static SiteGround exports without rebuilding, responsive Bacano media and
 signed temporary preview links.
 
+Product detail pages and technical catalog filters must follow
+[`STOREFRONT_PRODUCT_SPECIFICATIONS.md`](./STOREFRONT_PRODUCT_SPECIFICATIONS.md).
+
+Quantity-based web pricing is documented in
+[`STOREFRONT_VOLUME_PRICING.md`](./STOREFRONT_VOLUME_PRICING.md). Bacano owns
+the authoritative basket calculation; storefronts only render the effective
+prices and tier progress returned by the cart API.
+It documents the additive specification contract, static publication and the
+strict separation from commercial attributes and variants.
+
 #### Instalación y alcance de la skill
 
 El paquete incluye `skills/bacano-web`, una skill portátil para que un agente
@@ -107,6 +117,13 @@ profesional (`P1`) y mejoras (`P2`), para no bloquear una web por funciones
 apagadas. Sus informes usan estados claros con emojis: `✅ APROBADO`,
 `⚠️ ADVERTENCIA`, `❌ FALLÓ`, `➖ NO APLICA` y `🧪 NO VERIFICADO`.
 
+Además audita explícitamente la arquitectura **Static First** y la vista previa
+oficial. El informe incluye una sección “Arquitectura SDK y tráfico runtime” con
+instancias del cliente/provider, operaciones GraphQL observadas, duplicados,
+datos estáticos, actualizaciones vivas y evidencia de `noindex`, sitemap y cero
+marketing en preview. Cuando no puede capturar un trace real, lo declara como
+`🧪 NO VERIFICADO` en lugar de asumirlo desde el código.
+
 ### Entry points
 
 | Import                      | Contents                                              |
@@ -191,7 +208,8 @@ await client.init();
 
 `catalog.getProducts()` only returns products that are active, enabled for the
 website branch, have a valid `CLIENT` price and have available
-inventory in that branch warehouse.
+inventory in one of the inventory sources configured for the website. Websites
+without custom sources continue using the branch's default warehouse.
 
 ```typescript
 // List products
@@ -297,18 +315,28 @@ const recommendations = await client.catalog.getProductRecommendations({
   limit: 16,
 });
 
-// Related/sibling products configured in Bacano.
-// Use these to render product-level alternatives that are NOT real variants.
-// Each item is scoped to the current website branch and only includes active
-// catalog products.
+// Manually curated related products configured in Bacano.
+// Use these for recommendations, comparisons or complementary products.
+// Their public name always comes from the related product itself. Each item is
+// scoped to the current website branch and only includes active catalog items.
 for (const related of product?.relatedProducts ?? []) {
   console.log(related.productId);
   console.log(related.slug);
-  console.log(related.displayLabel ?? related.name);
+  console.log(related.name);
   console.log(related.sku);
   console.log(related.media[0]?.url);
 }
 
+// Customer-facing alternatives configured as one central option group.
+// The current product is included in members. Use displayLabel for the
+// selector and slug for navigation; keep relatedProducts for recommendations.
+if (product?.optionGroup) {
+  console.log(product.optionGroup.title);
+  for (const option of product.optionGroup.members) {
+    console.log(option.displayLabel ?? option.name, option.slug);
+  }
+}
+
 // Categories and brands
 const categories = await client.catalog.getCategories();
 const brands = await client.catalog.getBrands();
@@ -359,12 +387,19 @@ const availability = await client.catalog.checkAvailability([
 
 `maxPurchasableQuantity` is Bacano's current public purchase limit after active
 reservations, capped by the maximum accepted by public cart and checkout
-actions. It is not a raw warehouse inventory field. Use it to limit quantity
+actions. When a website uses multiple warehouses, this is the maximum that one
+source can fulfill; Bacano intentionally does not add stock from different
+warehouses. It is not a raw warehouse inventory field. Use it to limit quantity
 selectors and the total units of that variant already present in the local
 cart. Refresh the variants in one batch when opening the cart or checkout; do
 not request availability after every `+` click. This value can change after it
 is read, so Bacano still revalidates stock when checkout starts and finishes.
 
+At checkout, each order line is reserved in the first configured warehouse,
+by priority, that can fulfill that complete line. Different lines may use
+different warehouses, but Bacano does not split a single line between sources.
+The storefront does not implement this allocation or send warehouse IDs.
+
 ### 4. Local Cart And Checkout Start
 
 The website checkout remains guest-first. Buyer credentials and email
@@ -427,6 +462,9 @@ await client.cart.updateItem("cart-item-uuid", 5);
 // Remove by line id.
 await client.cart.removeItem("cart-item-uuid");
 
+// Discard the complete private cart and clear its SDK session.
+await client.cart.clear();
+
 // View current cart from the stored guest session.
 const currentCart = await client.cart.get();
 console.log(currentCart?.items); // CartItem[]
@@ -435,11 +473,21 @@ console.log(currentCart?.totals); // { subtotal, tax, discount, total }
 
 Cart rules:
 
-- No contact yet means local web cart only.
+- `cart.getOrCreate()` may create a private server cart without contact. This
+  is the supported path when the storefront needs authoritative stock, totals
+  or volume pricing before checkout.
+- Creating this browsing cart does not create delivery logistics. Delivery is
+  synchronized only by `cart.startCheckout()` after the customer selects the
+  fulfillment family.
 - Email, phone or a complete document pair can start a Bacano
   `sales_channel=WEB`, `PENDING + UNPAID` checkout.
 - `sales_channel=WEB`, `PENDING + UNPAID` without `order_number` means checkout started or abandoned.
 - These started checkouts are tracked by `orders.website_cart_status` and should be managed from Bacano's abandoned-cart view, not mixed into the normal sales list.
+- `cart.clear()` marks the private cart as `discarded`, preserves its audit
+  history and removes only `@bacano/sdk:cart:{websiteSlug}`. It never deletes
+  storage owned by the storefront.
+- Removing the final line also discards the server cart and clears its private
+  SDK session automatically.
 - The web must collect `fulfillmentFamily` before starting checkout:
   `SHIPPING` for delivery or `PICKUP` for store pickup.
 - The cart token is opaque. Bacano stores only its SHA-256 hash.
@@ -653,6 +701,23 @@ until `createPaymentSession` succeeds, then retires it. Payment response and
 retry pages must continue with the returned `orderId + publicOrderToken`; a
 second purchase starts a new cart instead of reusing the finalized order.
 
+The private `orderId + cartToken` session belongs exclusively to the SDK. A
+storefront must never read, remove or rewrite the
+`@bacano/sdk:cart:{websiteSlug}` key. When `cart.startCheckout()` discovers
+that a persisted session is no longer usable, Bacano returns the stable
+`INVALID_CART_TOKEN` or `CART_NOT_FOUND` code. The SDK then removes only that
+private session and retries the same start operation exactly once without a
+token. Storefront-owned product state is not touched, `checkout.submit()` is
+never repeated, and the failed token request creates no order. Other business
+errors preserve the private session and are returned with their stable code.
+
+Signing in after starting as a guest does not rotate the cart token. Bacano
+continues an unowned guest cart and can continue a cart already linked to the
+same authenticated buyer. Signing out, changing buyers, completing an order,
+or changing the website chain makes a non-matching private session
+non-recoverable for that browser identity, so the next start creates one fresh
+cart through the bounded recovery above.
+
 ### 6. Public Order Tracking
 
 Confirmation pages should not depend on browser-only snapshots. After a
@@ -785,6 +850,21 @@ createBacanoClient({
 identifier/token. Buyer access tokens are never persisted by Bacano SDK; the
 configured identity provider owns their lifecycle.
 
+### Website favicon
+
+The website's General settings can define one canonical favicon from Bacano's
+media library. It is returned by the existing public-config request, so a
+storefront does not need another API call or direct Storage integration:
+
+```tsx
+const publicConfig = await getWebsitePublicConfig({ apiUrl, websiteSlug });
+const faviconUrl = publicConfig.branding.favicon?.originalUrl;
+```
+
+Use `faviconUrl` in the framework's metadata or document head. When it is
+`null`, keep the storefront's packaged fallback icon. The public contract
+contains only browser-safe media metadata and a public Storage URL.
+
 ---
 
 ## React Integration
@@ -925,6 +1005,10 @@ await client.checkout.submit({
 `order_placed`, `purchase`, and `refund` are server-authoritative events. A
 storefront must never emit them from a thank-you page or payment response route.
 URLs are centrally sanitized to retain only approved UTM and click identifiers.
+Links and QR codes may additionally use `bacano_origin=<public-key>` to select a
+company-defined sales origin. The SDK preserves it with the attribution
+snapshot; Bacano validates it server-side and otherwise falls back to the
+normalized UTM/click-ID origin or `Web`.
 Google or Meta failures are isolated from catalog, cart, checkout, and payment.
 This isolation also applies to Bacano's server-side outbox producers: losing a
 marketing event must never roll back an order, payment, or refund transition.
@@ -1388,7 +1472,7 @@ function ProfilePage() {
 | `useProductFilters(opts?)`    | `{ data, loading, error, refetch }`                                                     | No            |
 | `useSearchSuggestions(opts?)` | `{ data, loading, error, refetch }`                                                     | No            |
 | `useAvailability(ids)`        | `{ data, loading, error, refetch }`                                                     | No            |
-| `useCart()`                   | `{ cart, loading, error, startCheckout, getOrCreate, addItem, updateItem, removeItem }` | No            |
+| `useCart()`                   | `{ cart, loading, error, startCheckout, getOrCreate, addItem, updateItem, removeItem, clear }` | No            |
 | `useCheckout()`               | `{ checkout, loading, error }`                                                          | No            |
 | `useOrders(opts?)`            | `{ data, loading, error, refetch }`                                                     | Yes           |
 | `useOrder(id)`                | `{ data, loading, error, refetch }`                                                     | Yes           |
@@ -1669,9 +1753,11 @@ import type {
 - **Two Hasura roles**: `public` for anonymous catalog and guest checkout, `customer` for optional account/order history features
 - **Only enabled price tiers are exposed** — `CLIENT` is always available;
   `SALE`, `WHOLESALE` and `WHOLESALE_2` appear only when enabled by the company
-- **Checkout remains retail** — Bacano charges a valid lower `SALE` price or
-  falls back to `CLIENT`; wholesale tiers are informational until a wholesale
-  checkout policy is explicitly implemented
+- **Checkout owns the final price** — Bacano charges a valid lower `SALE` price or
+  falls back to `CLIENT`; wholesale tiers become authoritative only when a
+  website enables the quantity-pricing policy described in
+  [`STOREFRONT_VOLUME_PRICING.md`](./STOREFRONT_VOLUME_PRICING.md). Otherwise
+  they remain informational.
 - **Raw inventory is abstracted** — `checkAvailability()` returns boolean + label, never raw quantities
 - **Company-scoped** — all queries are automatically filtered by `company_id` from the website context
 - **Local cart first** — the web keeps cart state locally until the visitor leaves email or phone

package/STOREFRONT_CONSTRUCTION.md

@@ -44,12 +44,22 @@ Después del gate se montan `ClerkProvider`, `BacanoProvider`,
 `BacanoMarketingProvider` y el resto del storefront. Puede entregarse
 `initialConfig` si el build ya obtuvo `public-config`; el gate vuelve a
 consultarlo antes de montar el sitio para detectar cambios posteriores al
-despliegue y evitar mostrar fugazmente el contenido estático.
+despliegue.
+
+Mientras confirma la configuración, el gate serializa `children` dentro de un
+`<noscript>` semántico. El catálogo, los productos, encabezados y enlaces siguen
+presentes en el HTML exportado y son visibles cuando JavaScript está
+deshabilitado, pero React no monta esos descendientes. Así evita cargar Clerk,
+GA4, Meta o Clarity y tampoco muestra fugazmente la tienda si construcción está
+activa. `loadingFallback` es únicamente la UI visible para navegadores con
+JavaScript durante esa consulta; por defecto permanece vacío.
 
 La pantalla oficial usa la imagen mobile hasta 767 px y la desktop desde 768
-px. En ambos casos emplea las fuentes responsivas generadas por Bacano. El
-storefront puede proporcionar `constructionFallback` si requiere una UI
-propia, pero no debe alterar la decisión `construction.enforced`.
+px. En ambos casos emplea las fuentes responsivas generadas por Bacano. Si solo
+existe una de las dos imágenes la reutiliza de forma segura; si no existe
+ninguna, conserva el fondo y muestra el título y mensaje configurados. El
+storefront puede proporcionar `constructionFallback` si requiere una UI propia,
+pero no debe alterar la decisión `construction.enforced`.
 
 ## Vista previa temporal
 
@@ -83,10 +93,13 @@ edge. El contrato del SDK y la configuración por website permanecen válidos.
 ## Checklist del storefront
 
 - `BacanoWebsiteGate` está por fuera de auth y marketing.
+- El export contiene el catálogo estático dentro del fallback `<noscript>`.
+- Sin JavaScript, catálogo, productos y enlaces continúan visibles.
 - La configuración se consulta en runtime con `cache: no-store`.
 - La pantalla activa no inicializa Clerk, GA4, Meta ni Clarity.
 - Localhost y dominios de desarrollo siguen mostrando la web.
 - Las imágenes desktop y mobile usan `srcset` y `sizes`.
 - El enlace temporal abre el storefront y desaparece de la barra de dirección.
 - Un token vencido no concede acceso y se elimina de `sessionStorage`.
+- La pantalla oficial sigue siendo útil aunque no tenga imágenes.
 - Un fallo de `public-config` degrada de forma abierta y no tumba el sitio.

package/STOREFRONT_MARKETING.md

@@ -178,6 +178,11 @@ en [`STOREFRONT_CLARITY.md`](./STOREFRONT_CLARITY.md).
   autenticación, OAuth o pago en nombres, URLs o parámetros.
 - La atribución se obtiene con `marketing.getAttribution()` y se entrega al
   contrato oficial de carrito/checkout.
+- `bacano_origin=<key-publica>` puede identificar un origen personalizado
+  configurado en Bacano. El SDK lo conserva durante la navegación y el backend
+  lo valida contra la empresa antes de asignarlo a la venta.
+- Si no existe esa key, Bacano normaliza UTM, referidor y click IDs a los
+  orígenes base; una venta web sin señal reconocida conserva `Web` como origen.
 - La autorización publicitaria del checkout es opcional, separada y nunca
   bloquea la compra.
 - Los datos de contacto solo pueden normalizarse y hashearse en el backend bajo

package/STOREFRONT_PERFORMANCE.md

@@ -93,6 +93,17 @@ available was reached. Do not poll after every click or persist the limit as
 catalog data: another checkout may consume stock, and Bacano remains
 authoritative when checkout starts and finishes.
 
+For websites configured with multiple inventory sources, the cap is the
+largest quantity fulfillable by a single source, not the sum of all warehouses.
+Bacano assigns each complete order line to the first prioritized warehouse that
+can fulfill it. Storefronts must never choose, expose or combine warehouses.
+
+Post-sale inventory follows the same ownership rules. A returned item goes back
+to the warehouse that fulfilled the original order line. An outgoing replacement
+for a web exchange is assigned to the first current website inventory source
+that can fulfill the complete replacement quantity. Pausing the website does not
+block post-sale processing for orders placed while it was active.
+
 ## Responsive media
 
 Every SDK product/content media object can expose `responsiveSources`. Use it
@@ -248,6 +259,32 @@ checkout, sign-in and customer account pages. Public catalog and product pages
 must not download an authentication runtime merely because buyer accounts are
 enabled for the website.
 
+## Runtime traffic audit
+
+A Static First review is incomplete without a real browser trace. Capture a
+fresh direct load separately from internal navigation, catalog interaction and
+product navigation. For every GraphQL request record its `operationName`,
+variables, initiator, phase and status.
+
+The report must distinguish:
+
+- data already present in exported HTML or the static bootstrap;
+- volatile price, availability and purchase-limit refreshes;
+- structural catalog requests caused by an explicit filter or pagination;
+- duplicated operations with equivalent variables and no intervening
+  invalidation or user action.
+
+The initial public route must not download full products already represented by
+the bootstrap. Live-state requests must group and deduplicate variant IDs,
+respect the documented batch limit and keep a failure-safe cache. A documented
+revalidation is not a duplicate, but its reason and ownership must be visible in
+the trace.
+
+Also record the number of `BacanoClient` and `BacanoProvider` instances and
+confirm that server/build `public-config` becomes the provider's
+`initialContext`. If a browser trace cannot be captured, mark this control as
+not verified instead of inferring it from source code.
+
 ## Acceptance checklist for storefront agents
 
 - [ ] View source contains real product cards/details, not only skeletons.
@@ -263,3 +300,5 @@ enabled for the website.
 - [ ] Mobile and desktop Lighthouse runs show no material layout shift.
 - [ ] A production trace confirms no duplicated catalog, shipping or website
       bootstrap calls during the first navigation.
+- [ ] The trace lists operation names and separates static, live and
+      interaction-driven data.

package/STOREFRONT_PREVIEW.md

@@ -451,6 +451,29 @@ Baby Rex is the implementation reference for integration shape, not a source to
 copy blindly. Other storefronts keep their own route maps, Content keys,
 mappers, and visual components.
 
+## Preview audit contract
+
+An audit must verify both the SDK lifecycle and the storefront result model.
+The SDK lifecycle is `idle`, `loading`, `ready` or `error`; `missing` and
+`unsupported` are storefront document/view outcomes and must not be presented
+as extra SDK statuses.
+
+At minimum, automate or capture evidence for:
+
+- a direct request to the single preview route returning `noindex, nofollow`;
+- the preview route being absent from every sitemap;
+- reuse of the global `BacanoProvider` and initialized `BacanoClient`;
+- a finite route allowlist that rejects account, checkout, payment and order
+  routes;
+- absence of GA4, Meta, Clarity and other effective marketing scripts, requests
+  and events on a direct preview load;
+- `idle -> loading -> ready`, safe error, missing and unsupported rendering;
+- cache reuse, forced refresh and internal navigation;
+- unchanged static HTML, route generation and sitemap for public pages.
+
+The final report must name the requests observed in preview and distinguish an
+unexecuted browser check from a passing zero-request assertion.
+
 ## Short checklist for agents
 
 - [ ] Use `@bacano/sdk` `1.0.5` or newer.
@@ -461,6 +484,8 @@ mappers, and visual components.
 - [ ] Keep preview `noindex`, outside the sitemap, and free of transactional routes.
 - [ ] Hide root-level commercial UI and verify zero marketing events in preview.
 - [ ] Test idle, loading, ready, safe error, refresh, cache, and navigation states.
+- [ ] Test storefront-specific missing and unsupported outcomes.
+- [ ] Capture a direct preview trace proving zero effective marketing traffic.
 - [ ] Verify static public pages and their build output remain unchanged.
 - [ ] Run typecheck, lint, unit tests, E2E, and the complete production build.
 

package/STOREFRONT_PRODUCT_SPECIFICATIONS.md

@@ -0,0 +1,127 @@
+# Fichas técnicas de producto en storefronts
+
+Este documento define el contrato público de `@bacano/sdk` para mostrar y
+filtrar la información técnica creada por cada comercio en Bacano Content.
+
+La capacidad es independiente de los atributos y variantes comerciales. Las
+variantes continúan siendo la fuente de combinaciones, SKU, precio e
+inventario; una ficha técnica no debe usarse para recrearlas ni modificarlas.
+
+## Lectura en detalle y builds estáticos
+
+`Product.specification` contiene la ficha técnica efectiva del producto o
+`null` cuando no existe una ficha pública con valores. Está disponible en:
+
+- `client.catalog.getProduct()`;
+- `client.catalog.getProductBySlug()`;
+- los productos de `client.catalog.getStaticCatalogBootstrap()`;
+- los productos devueltos por `client.catalog.getCatalogPage()`.
+
+Las tiendas estáticas deben consumir el valor que llega en el bootstrap. Un
+cambio público en la definición o los valores requiere **Publicar cambios** y
+un nuevo build del storefront. Stock, precios y descuentos conservan su flujo
+dinámico independiente.
+
+```tsx
+import type { ProductSpecification } from "@bacano/sdk";
+
+export function ProductTechnicalSpecification({
+  specification,
+}: {
+  specification: ProductSpecification | null;
+}) {
+  if (!specification) return null;
+
+  return (
+    <section aria-labelledby="technical-specification-title">
+      <h2 id="technical-specification-title">Información adicional</h2>
+      {specification.sections.map((section) => (
+        <div key={section.id ?? section.key}>
+          <h3>{section.title}</h3>
+          {section.description ? <p>{section.description}</p> : null}
+          <dl>
+            {section.fields.map((field) => (
+              <div key={field.id}>
+                <dt>{field.label}</dt>
+                <dd>{formatSpecificationValue(field.value)}</dd>
+              </div>
+            ))}
+          </dl>
+        </div>
+      ))}
+    </section>
+  );
+}
+
+function formatSpecificationValue(value: unknown): string {
+  if (typeof value === "boolean") return value ? "Sí" : "No";
+  if (typeof value === "string" || typeof value === "number") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map(formatSpecificationValue).join(", ");
+  }
+  if (value && typeof value === "object") {
+    if ("label" in value && typeof value.label === "string") {
+      return value.label;
+    }
+    if ("unit" in value && "value" in value) {
+      const measure = value as {
+        value: number;
+        unit: { symbol: string };
+      };
+      return `${measure.value} ${measure.unit.symbol}`;
+    }
+  }
+  return "";
+}
+```
+
+Los campos vacíos o internos ya son omitidos por Bacano. El storefront recibe
+la organización por secciones y puede reproducirla o aplicar su propio diseño.
+No debe consultar Hasura, interpretar el JSON editable ni reconstruir unidades
+u opciones por su cuenta.
+
+## Facetas técnicas
+
+Solicitar `filters: true` en `getCatalogPage()` devuelve
+`result.filters.technical`. Cada faceta expone un `fieldId` estable, tipo,
+rango, unidad, opciones y conteos relevantes para los productos públicos y
+vendibles del resultado.
+
+```ts
+const page = await client.catalog.getCatalogPage({
+  categoryListKey: "categorias",
+  attributeListKey: "atributos",
+  categorySlug: "vehiculos-electricos",
+  technicalByField: {
+    "FIELD_UUID_AUTONOMIA": { min: 40, max: 120 },
+    "FIELD_UUID_BATERIA": { optionIds: ["OPTION_UUID_LITIO"] },
+  },
+  include: { products: true, filters: true },
+});
+```
+
+Reglas del filtro:
+
+- los valores seleccionados dentro de una misma faceta se combinan con OR;
+- las facetas diferentes se combinan con AND;
+- número y medida aceptan `min` y `max`;
+- fecha acepta `dateFrom` y `dateTo`;
+- booleano acepta `booleanValues`;
+- lista simple o múltiple acepta `optionIds`;
+- el storefront solo debe enviar IDs publicados por `filters.technical`.
+
+Bacano rechaza como filtro cualquier campo interno, oculto o no marcado como
+filtrable aunque se intente enviar su UUID manualmente.
+
+## Reglas de integración
+
+- No crear GraphQL directo ni consultar el JSON flexible de Content.
+- No persistir una segunda copia de la ficha en el storefront.
+- No convertir fichas técnicas en atributos o variantes.
+- No inventar facetas para campos que Bacano no publica como filtrables.
+- Conservar el orden de secciones, campos y opciones entregado por el SDK.
+- Omitir por completo el bloque cuando `specification` sea `null`.
+- Validar el build estático con productos con y sin ficha antes de publicar.
+

package/STOREFRONT_VOLUME_PRICING.md

@@ -0,0 +1,131 @@
+# Precios por cantidad en storefronts
+
+Este documento define el contrato oficial para mayoreo por cantidad en sitios
+web Bacano. El storefront no calcula, copia ni fuerza precios: Bacano resuelve
+el carrito completo en cada cambio y vuelve a validarlo al cerrar la compra.
+
+## Configuración
+
+La política pertenece a un `website_id`. El comercio activa un primer umbral
+para `WHOLESALE` y, si tiene habilitado ese tipo de precio, puede configurar un
+segundo umbral para `WHOLESALE_2`.
+
+- Solo participan variantes con un precio `WHOLESALE` válido para la sucursal
+  del website.
+- La cantidad elegible es la suma de unidades participantes del carrito, no la
+  cantidad de una única línea.
+- Al alcanzar el segundo nivel, una variante sin `WHOLESALE_2` conserva su
+  precio `WHOLESALE`.
+- Un nivel mayorista nunca reemplaza un precio regular o promocional menor.
+- Las variantes sin precio mayorista siguen comprándose a su mejor precio
+  regular, pero no suman para alcanzar el umbral.
+
+## Configuración pública
+
+`getWebsitePublicConfig()` expone únicamente los umbrales públicos necesarios
+para comunicar la promoción:
+
+```ts
+const config = await getWebsitePublicConfig({
+  apiUrl,
+  websiteSlug,
+  origin,
+});
+
+config.volumePricing;
+// {
+//   schemaVersion: 1,
+//   enabled: true,
+//   tiers: [
+//     { priceType: "WHOLESALE", minQuantity: 3 },
+//     { priceType: "WHOLESALE_2", minQuantity: 6 }
+//   ]
+// }
+```
+
+Este bloque sirve para mensajes generales. No debe usarse para calcular el
+precio final porque la elegibilidad depende de los precios vigentes de cada
+variante y del carrito completo.
+
+## Respuesta del carrito
+
+Las operaciones `cart.getOrCreate()`, `cart.get()`, `cart.setItem()`,
+`cart.removeItem()` y `cart.startCheckout()` devuelven:
+
+```ts
+cart.volumePricing;
+// {
+//   enabled: true,
+//   eligibleQuantity: 4,
+//   appliedPriceType: "WHOLESALE",
+//   appliedMinQuantity: 3,
+//   nextPriceType: "WHOLESALE_2",
+//   nextMinQuantity: 6,
+//   remainingQuantity: 2,
+//   totalSavings: 24000
+// }
+
+cart.items[0];
+// {
+//   baseUnitPrice: 50000,
+//   unitPrice: 42000,
+//   lineTotal: 126000,
+//   unitSavings: 8000,
+//   lineSavings: 24000,
+//   volumePricingEligible: true,
+//   resolvedPriceType: "WHOLESALE",
+//   volumePricingMinQuantity: 3,
+//   ...
+// }
+```
+
+El storefront debe pintar `unitPrice`, `lineTotal` y los totales retornados por
+Bacano. `baseUnitPrice`, `unitSavings`, `lineSavings` y `totalSavings` permiten
+explicar el cambio sin reconstruir reglas. `volumePricingEligible` indica si la
+línea participa en los umbrales, incluso antes de alcanzar uno.
+
+Al cambiar una cantidad debe esperar la respuesta de `setItem()` antes de
+confirmar visualmente el nuevo total. La experiencia recomendada es mostrar el
+precio anterior tachado cuando exista ahorro, el nivel aplicado y un mensaje
+como “Agrega 2 unidades más para obtener Mayorista 2” usando
+`remainingQuantity`. Si `volumePricing.enabled` es `false`, no debe mostrarse
+ninguna comunicación de mayoreo.
+
+## Sincronización antes del checkout
+
+El precio por cantidad no depende del correo ni de la identidad del comprador.
+Para mostrarlo desde el carrito, el storefront debe crear o recuperar la sesión
+privada con `cart.getOrCreate()` al agregar la primera unidad y utilizar
+`cart.setItem()` después de cada cambio. `cart.startCheckout()` incorpora el
+contacto y vuelve a validar los mismos precios de forma autoritativa.
+
+El carrito privado puede existir sin correo, teléfono ni identidad. Su creación
+no inicia la logística: Bacano crea o sincroniza la entrega únicamente cuando
+el storefront llama `cart.startCheckout()` con la modalidad elegida.
+
+El storefront conserva bajo su responsabilidad los datos visuales que necesite
+(imagen, slug o atributos), pero no precios ni totales autoritativos. Para
+vaciar el carrito debe llamar `cart.clear()`: Bacano lo marca como descartado y
+el SDK elimina exclusivamente su sesión privada. Quitar la última línea produce
+el mismo cierre automáticamente. Ninguna de estas operaciones borra el carrito
+local propio del storefront; ese almacenamiento se limpia después de recibir la
+confirmación del SDK.
+
+## Checkout y concurrencia
+
+El checkout vuelve a resolver precios, stock y cupones de forma autoritativa.
+Los valores locales son únicamente una vista optimista. Una modificación de
+precios, inventario o política entre la vista del carrito y el checkout puede
+producir una respuesta actualizada o un error comercial controlado.
+
+Los pedidos conservan por línea el tipo de precio resuelto y el umbral aplicado
+como evidencia. La configuración futura del website no cambia el pedido ya
+confirmado.
+
+## Prohibiciones
+
+- No calcular umbrales en Baby Rex ni en otro storefront.
+- No seleccionar `WHOLESALE` directamente desde el navegador.
+- No enviar precios en operaciones de carrito o checkout.
+- No consultar Hasura ni tablas de precios mediante GraphQL directo.
+- No aplicar descuentos paralelos para simular mayoreo.

package/client.d.ts

@@ -45,6 +45,7 @@ export interface BacanoClient {
             quantity: number;
         }>;
         removeItem(cartItemId: string): Promise<Cart>;
+        clear(): Promise<void>;
     };
     checkout: {
         getLocationOptions(): Promise<WebsiteLocationOptions>;