@bacano/sdk 1.0.1 → 1.1.8

package/README.md

@@ -21,13 +21,135 @@ React hooks are available from `@bacano/sdk/react` and require `react >= 18`
 as a peer dependency. The core client has no runtime dependencies and works
 without React.
 
+### Auditoría del storefront
+
+El SDK incluye la skill oficial `bacano-web`. Instalarla al iniciar un
+storefront y ejecutarla antes de publicar o después de un cambio relevante del
+SDK, hosting, autenticación, pagos o medición:
+
+```bash
+pnpm add @bacano/sdk
+pnpm exec bacano-web install --agent all
+pnpm exec bacano-web check
+```
+
+Después invocarla desde el agente elegido:
+
+- Codex: `$bacano-web`
+- Claude Code: `/bacano-web`
+- Antigravity: solicitar una auditoría Bacano Web o elegirla desde `/skills`
+
+`install` solo instala una copia canónica de la skill y sus enlaces de
+descubrimiento. `check` confirma que está vigente. Ninguno ejecuta la auditoría,
+modifica el storefront ni despliega; esa revisión comienza únicamente cuando
+el usuario o agente invoca la skill.
+
+Every storefront must follow [`STOREFRONT_MARKETING.md`](./STOREFRONT_MARKETING.md)
+when instrumenting analytics, advertising signals, contact actions, ecommerce
+events, attribution, or preview behavior. It is the canonical implementation
+contract for storefront agents and ships inside the npm package.
+
+Commercial forms and newsletter subscriptions must follow
+[`STOREFRONT_LEADS.md`](./STOREFRONT_LEADS.md). Storefronts own the form UI;
+Bacano owns consent evidence, identity resolution, attribution and idempotent
+lead capture through the SDK.
+
+Static and hybrid stores must also follow
+[`STOREFRONT_PERFORMANCE.md`](./STOREFRONT_PERFORMANCE.md). It defines the
+official build bootstrap, live-state refresh, responsive media and request
+ownership rules. It also documents the shared public-config bootstrap, deferred
+marketing scripts and route-scoped authentication required for fast public
+catalog pages.
+
+Storefronts that can be hidden temporarily must mount the runtime gate defined
+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
+audite el repositorio, build y dominio antes de producción. Primero confirma si
+el proyecto es una **web informativa** o una **tienda virtual** y aplica un
+checklist distinto; no exige carrito, checkout o pagos a un sitio informativo.
+
+Ubicaciones del proyecto después de instalar la skill:
+
+| Agente      | Ruta de descubrimiento      | Invocación                    |
+| ----------- | --------------------------- | ----------------------------- |
+| Codex       | `.codex/skills/bacano-web`  | `$bacano-web`                 |
+| Claude Code | `.claude/skills/bacano-web` | `/bacano-web`                 |
+| Antigravity | `.agents/skills/bacano-web` | Solicitud natural o `/skills` |
+
+Para instalarla solo para un agente puede indicarse explícitamente:
+
+```bash
+pnpm exec bacano-web install --agent antigravity
+```
+
+También puede ejecutarse sin `--agent`; en una terminal interactiva pregunta si
+se usará Antigravity, Claude Code, Codex o todos. Mantiene una sola copia física
+en `.agents/skills/bacano-web` y crea enlaces de descubrimiento para los otros
+agentes seleccionados.
+
+```bash
+pnpm exec bacano-web check
+```
+
+El paquete incluye un aviso `postinstall` como ayuda adicional, aunque algunos
+gestores pueden ocultar su salida. El aviso nunca modifica el repositorio y
+puede desactivarse en entornos controlados con
+`BACANO_SDK_HIDE_SKILL_NOTICE=1`.
+
+La skill realiza auditorías de solo lectura por defecto. Primero detecta las
+capacidades realmente activas y separa gates de publicación (`P0`), calidad
+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 |
-| --- | --- |
-| `@bacano/sdk` | Core client, catalog, cart, checkout, orders, profile |
-| `@bacano/sdk/react` | `BacanoProvider` and React hooks |
-| `@bacano/sdk/graphql` | Raw GraphQL documents, for advanced use |
+| Import                      | Contents                                              |
+| --------------------------- | ----------------------------------------------------- |
+| `@bacano/sdk`               | Core client, catalog, cart, checkout, orders, profile |
+| `@bacano/sdk/react`         | `BacanoProvider` and React hooks                      |
+| `@bacano/sdk/react/preview` | Optional live preview controller and toolbar          |
+| `@bacano/sdk/graphql`       | Raw GraphQL documents, for advanced use               |
+
+---
+
+## Live Content Preview
+
+Static storefronts can show current published Bacano Content without rebuilding
+their public pages. Import the isolated preview entrypoint only from the
+storefront preview route:
+
+```tsx
+import { BacanoPreviewShell } from "@bacano/sdk/react/preview";
+```
+
+The public storefront remains static. Preview V1 never exposes drafts and
+automatically disables the SDK marketing runtime inside its tree. See
+[`STOREFRONT_PREVIEW.md`](./STOREFRONT_PREVIEW.md), the canonical contract for
+provider hierarchy, responsibilities, security, agent checklist, and the
+validated Baby Rex reference implementation.
 
 ---
 
@@ -86,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
@@ -148,6 +271,43 @@ const filtered = await client.catalog.getProducts({
 // Single product
 const product = await client.catalog.getProduct("product-uuid");
 
+// Static builds: fetch the complete sellable catalog and its first renderable
+// catalog page. This is the canonical source for initial HTML, routes,
+// metadata, sitemap and product page data.
+const bootstrap = await client.catalog.getStaticCatalogBootstrap({
+  categoryListKey: "categorias-web",
+  attributeListKey: "atributos",
+  pageSize: 100,
+  initialPageSize: 24,
+  maxProducts: 10_000,
+  sortBy: "name_asc",
+});
+
+const productByRoute = new Map(
+  bootstrap.products.map((item) => [item.slug || item.id, item]),
+);
+
+// Cards and filters use product.variants. Detail selectors use the official
+// helper so sold-out sizes remain visible and older snapshots stay compatible.
+const detailVariants = getProductDetailVariants(product!);
+
+// Do not call getProductBySlug() once per route during the same build.
+// Reuse productByRoute from the snapshot instead.
+// Render bootstrap.initialPage in the initial catalog HTML instead of
+// publishing an empty skeleton that waits for a browser request.
+
+// After hydration, refresh only volatile state for visible variants.
+const liveState = await client.catalog.getProductLiveState(
+  detailVariants.map((variant) => variant.id),
+);
+// Each item includes maxPurchasableQuantity for product and cart controls.
+
+// Responsive storage candidates are provided by the SDK.
+const srcSet = formatMediaSrcSet(product.media[0]?.responsiveSources ?? []);
+
+// Editorial ContentMedia uses heroUrl plus intrinsic-width-aware
+// responsiveSources. See STOREFRONT_PERFORMANCE.md for the <picture> contract.
+
 // Automatic recommendations for the product detail. This is an independent,
 // lightweight request; Bacano resolves ranking, availability and public price.
 const recommendations = await client.catalog.getProductRecommendations({
@@ -155,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();
@@ -211,9 +381,25 @@ const availability = await client.catalog.checkAvailability([
   "variant-uuid-1",
   "variant-uuid-2",
 ]);
-// → [{ productVariantId, inStock: true, label: "In Stock" }]
+// → [{ productVariantId, inStock: true, label: "In Stock",
+//      maxPurchasableQuantity: 8 }]
 ```
 
+`maxPurchasableQuantity` is Bacano's current public purchase limit after active
+reservations, capped by the maximum accepted by public cart and checkout
+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
@@ -276,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[]
@@ -284,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.
@@ -337,6 +536,20 @@ collecting contact or address data. Bacano resolves current prices, stock,
 website and shipping policy; the storefront must format the structured values
 instead of hardcoding or recalculating them.
 
+For the policy to be enabled, the website must have delivery enabled, a
+positive free-shipping threshold, and at least one active shipping service
+enabled for that website whose collection mode charges shipping with the sale
+(`with_sale`). Shipping collected directly by the carrier is intentionally not
+overridden by this promotion. These prerequisites are configured in Bacano;
+the storefront must not infer or reproduce them.
+
+`getShippingPolicy()` is cached for five minutes per SDK client. This keeps
+catalog navigation from repeatedly requesting the same configuration. After
+changing the policy in Bacano, recreate the client or reload the storefront to
+validate it immediately. `getFreeShippingProgress()` always validates the
+submitted variants and quantities against Bacano's current prices and returns
+`enabled: false` with nullable amounts when the policy does not apply.
+
 `getShippingQuotes` returns the final shipping price for an address. Before a
 guest checkout exists, pass `items`. Once an active cart session exists, the
 SDK intentionally prefers the persisted cart and ignores loose items so
@@ -488,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
@@ -620,10 +850,189 @@ 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
 
+### Storefront marketing and measurement
+
+GA4, Meta, and Microsoft Clarity are configured per website in Bacano and are
+disabled by default.
+The existing public-config request returns only active public destination IDs;
+provider secrets never reach the SDK. The runtime remains a no-op outside the
+website's canonical production domain.
+
+Mount one provider at the storefront root, using the same public config already
+loaded for buyer accounts:
+
+```tsx
+import { getWebsitePublicConfig } from "@bacano/sdk";
+import { BacanoMarketingProvider, useMarketing } from "@bacano/sdk/react";
+
+const publicConfig = await getWebsitePublicConfig({ apiUrl, websiteSlug });
+
+<BacanoMarketingProvider publicConfig={publicConfig}>
+  <Storefront />
+</BacanoMarketingProvider>;
+
+function AddToCartButton({ variant }) {
+  const marketing = useMarketing();
+
+  async function add() {
+    await updateCartSuccessfully(variant.id);
+    marketing.track({
+      eventName: "add_to_cart",
+      value: variant.price,
+      items: [
+        {
+          itemId: variant.id, // always product_variant_id
+          itemName: variant.productName,
+          sku: variant.sku,
+          price: variant.price,
+          quantity: 1,
+        },
+      ],
+    });
+  }
+
+  return <button onClick={add}>Add to cart</button>;
+}
+```
+
+The browser contract is versioned and accepts `page_view`, `search`,
+`view_item_list`, `select_item`, `view_item`, `add_to_cart`,
+`remove_from_cart`, `view_cart`, `begin_checkout`, `add_shipping_info`,
+`add_payment_info`, and `contact`. Emit events only after the related operation
+has succeeded. Use one manual `page_view` source for SPA navigation because the
+GA4 adapter disables automatic page views.
+
+When Microsoft Clarity is active, this same provider loads it automatically and
+forwards canonical browser events as Clarity custom events. Do not install a
+second Clarity snippet or package in the storefront. Setup, privacy, and
+verification are documented in [`STOREFRONT_CLARITY.md`](./STOREFRONT_CLARITY.md).
+
+Contact actions can identify their stable storefront location with the optional
+`contactPlacement` field. It accepts only `product_detail`, `floating`,
+`header`, `footer`, or `contact_page`; visible labels and arbitrary strings are
+not part of the public contract. The runtime ignores the field on events other
+than `contact`.
+
+```tsx
+marketing.track({
+  eventName: "contact",
+  contactMethod: "email",
+  contactPlacement: "footer",
+});
+```
+
+A product contact keeps the same variant identity, value, and item payload used
+by the ecommerce events:
+
+```tsx
+marketing.track({
+  eventName: "contact",
+  contactMethod: "whatsapp",
+  contactPlacement: "product_detail",
+  value: price * quantity,
+  items: [
+    {
+      itemId: variant.id,
+      itemName: product.name,
+      sku: variant.sku,
+      price,
+      quantity,
+      itemBrand: product.brand?.name,
+      itemCategory: product.category,
+      itemVariant: "Talla: 12 meses / Color: Rosado",
+    },
+  ],
+});
+```
+
+GA4 receives this field as `contact_placement`; Meta receives the same
+`contact_placement` key while preserving `contact_method`, `content_ids`, and
+`contents`.
+
+For checkout selectors, an automatic default is not yet a customer choice.
+Emit `add_shipping_info` and `add_payment_info` immediately for an explicit,
+valid selection, or once after a successful checkout submission when the
+customer kept an automatic default. Deduplicate both paths with the selected
+delivery/payment identity. On product lists, `itemId` and `price` must come
+from the same public, price-bearing variant; the advertised variant is the
+lowest-price variant with stable `order` and ID tie-breakers.
+
+Transfer the runtime attribution snapshot when checkout starts and again when
+it is submitted. Bacano freezes the touchpoints on the order; the second
+snapshot may only fill missing GA4 `client_id` and `session_id` values that the
+Google tag resolved asynchronously:
+
+```typescript
+await client.cart.startCheckout({
+  contact,
+  items,
+  marketingAttribution: marketing.getAttribution() ?? undefined,
+});
+
+await client.checkout.submit({
+  contact,
+  marketingAttribution: marketing.getAttribution() ?? undefined,
+  advertisingConsent: publicConfig.marketing.consentPolicy
+    ? {
+        policyId: publicConfig.marketing.consentPolicy.id,
+        policyVersion: publicConfig.marketing.consentPolicy.version,
+        statementHash: publicConfig.marketing.consentPolicy.statementHash,
+        granted: optionalAdvertisingCheckbox,
+      }
+    : undefined,
+});
+```
+
+`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.
+The runtime captures GA4 browser identity and Meta browser context (`fbp`,
+`fbc`, and user agent) internally, so storefronts must not read cookies or
+construct provider identifiers themselves. Contact information remains governed
+by the website's explicit advertising-consent policy.
+
+An active, validated integration can enable a temporary diagnostic window from
+Bacano. GA4 events receive `debug_mode`; Meta server events receive its encrypted
+Test Events code. The mode is off by default, expires automatically, is cleared
+when an integration is paused or reconfigured, and never exposes the Meta code
+through public config or the SDK.
+
+The canonical contract and acceptance checklist live in
+`docs/websites/MARKETING_MEASUREMENT_STOREFRONTS_CHECKLIST.md` in the Bacano ERP
+repository.
+
+Website legal documents and the optional informational cookie notice are
+available in `publicConfig.legal`. Their canonical contract lives in
+[`STOREFRONT_LEGAL.md`](./STOREFRONT_LEGAL.md), which ships inside this package.
+The notice does not gate the marketing runtime; storefronts must not reinterpret
+it as a consent manager.
+
 ### Setup
 
 Wrap your app with `BacanoProvider`:
@@ -1063,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           |
@@ -1223,6 +1632,7 @@ The SDK throws typed errors you can catch and handle:
 ```typescript
 import {
   WebsiteError,
+  RateLimitError,
   AuthError,
   CheckoutError,
   NotInitializedError,
@@ -1248,6 +1658,8 @@ try {
     console.log("GraphQL errors:", err.graphqlErrors);
   } else if (err instanceof NotInitializedError) {
     // client.init() was not called
+  } else if (err instanceof RateLimitError) {
+    console.log("Retry after seconds:", err.retryAfterSeconds);
   } else if (err instanceof WebsiteError) {
     // Other SDK error (network, rate limit, etc.)
     console.log("Error code:", err.code);
@@ -1257,6 +1669,11 @@ try {
 }
 ```
 
+`RATE_LIMITED` errors expose `status = 429` and `retryAfterSeconds`. Normal SDK
+operations do not retry mutations automatically. The static catalog snapshot
+is a read-only build contract and safely retries up to four times, never before
+the server's `Retry-After` window and with a three-minute cumulative wait cap.
+
 Common setup errors:
 
 | Code / message      | Meaning                                        | Fix                                                            |
@@ -1296,7 +1713,7 @@ import type {
   ProductCategory,
   ProductSubcategory,
   Brand,
-  ProductAvailability, // { productVariantId, inStock, label }
+  ProductAvailability, // { productVariantId, inStock, label, maxPurchasableQuantity }
   GetProductsOptions, // { categoryName, search, colors, tags, minPrice, maxPrice, inStock, attributes, sortBy, ... }
   GetProductFiltersOptions,
   ProductFilters, // { categories, brands, colors, priceRange, attributes }
@@ -1304,6 +1721,8 @@ import type {
   ProductSortBy, // 'name_asc' | 'name_desc' | 'price_asc' | 'price_desc' | 'newest'
   SearchSuggestion, // { type: 'product' | 'brand' | 'category', text, id? }
   GetSearchSuggestionsOptions,
+  GetStaticCatalogSnapshotOptions,
+  StaticCatalogSnapshot,
 
   // Cart
   StartGuestCheckoutInput,
@@ -1334,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