@bacano/sdk 1.0.1 → 1.1.8

package/STOREFRONT_MARKETING.md

@@ -0,0 +1,291 @@
+# Marketing y medición en storefronts Bacano
+
+Este documento es el contrato canónico para agentes y equipos que construyen un
+storefront con `@bacano/sdk`. Una tienda no debe inventar nombres de eventos,
+identificadores, adaptadores ni llamadas directas a proveedores.
+
+## Regla principal
+
+El storefront expresa hechos mediante `useMarketing().track()`. El SDK decide
+si la medición está activa, sanea la URL y adapta el evento a GA4, Meta y
+Microsoft Clarity. Nunca
+se debe llamar directamente a `gtag`, `dataLayer`, `fbq`, Measurement Protocol
+o Conversions API.
+Clarity también se carga desde este runtime; no se instala su snippet de forma
+paralela.
+
+```tsx
+import { useMarketing } from "@bacano/sdk/react";
+
+const marketing = useMarketing();
+
+marketing.track({
+  eventName: "contact",
+  contactMethod: "whatsapp",
+  contactPlacement: "product_detail",
+});
+```
+
+Un contacto general usa el mismo contrato sin inventar un producto:
+
+```tsx
+marketing.track({
+  eventName: "contact",
+  contactMethod: "email",
+  contactPlacement: "contact_page",
+});
+```
+
+La caída o ausencia de marketing nunca puede bloquear catálogo, carrito,
+checkout, pago, autenticación o navegación. En localhost, preview y orígenes no
+canónicos el runtime es un `no-op` seguro.
+
+## Identidades estables
+
+- `WebsiteMarketingItem.itemId` siempre es `product_variant_id` de Bacano.
+- SKU es información complementaria; nunca reemplaza `itemId`.
+- Un evento de producto debe usar la variante realmente visible o elegida.
+- `order_id` es el `transaction_id` de conversiones autoritativas.
+- Los nombres, precios, cantidades y atributos deben corresponder al mismo
+  instante y variante.
+
+Estas reglas permiten que eventos, feeds de catálogo, públicos y conversiones
+se relacionen sin depender del slug o de la ruta del storefront.
+
+## Cuándo emitir cada evento
+
+| Evento              | Emitir después de                      | No emitir por                      |
+| ------------------- | -------------------------------------- | ---------------------------------- |
+| `page_view`         | Navegación resuelta y renderizada      | Cada render de React               |
+| `search`            | Resultados válidos para una búsqueda   | Cada tecla                         |
+| `view_item_list`    | Lista visible con items reales         | Skeleton o respuesta fallida       |
+| `select_item`       | Selección que inicia navegación válida | Hover                              |
+| `view_item`         | Producto y variante cargados           | Cambio irrelevante de estado       |
+| `add_to_cart`       | Carrito actualizado                    | Clic antes de conocer el resultado |
+| `remove_from_cart`  | Carrito actualizado                    | Intento fallido                    |
+| `view_cart`         | Carrito abierto con su contenido       | Montaje global de providers        |
+| `begin_checkout`    | Carrito sincronizado con Bacano        | Abrir un modal sin sincronizar     |
+| `add_shipping_info` | Entrega elegida o confirmada           | Valores predeterminados invisibles |
+| `add_payment_info`  | Método elegido o confirmado            | Método aún inválido                |
+| `contact`           | Apertura intencional del canal         | Render del botón                   |
+
+`purchase`, `order_placed` y `refund` son eventos autoritativos del backend. El
+storefront nunca los emite desde una página de éxito o respuesta de pago.
+
+## Payload de productos
+
+```tsx
+marketing.track({
+  eventName: "add_to_cart",
+  value: unitPrice * quantity,
+  items: [
+    {
+      itemId: selectedVariant.id,
+      itemName: product.name,
+      sku: selectedVariant.sku,
+      price: unitPrice,
+      quantity,
+      itemBrand: product.brand?.name,
+      itemCategory: product.category,
+      itemVariant: selectedVariant.attributes
+        .map((attribute) => attribute.value)
+        .join(" / "),
+    },
+  ],
+});
+```
+
+- `value` representa el valor total de los items del evento.
+- `price` es unitario y `quantity` es positiva.
+- No se deben enviar productos ocultos, precios aproximados ni la primera
+  variante por conveniencia si el comprador eligió otra.
+- El storefront no envía PII dentro de eventos de navegador.
+
+## Contactos y WhatsApp
+
+Todo enlace de WhatsApp, teléfono o correo debe emitir `contact`. Esto mide la
+apertura del canal; no demuestra que el comprador haya enviado un mensaje o que
+el comercio lo haya atendido.
+
+Valores de `contactMethod`:
+
+- `whatsapp`
+- `phone`
+- `email`
+
+Valores de `contactPlacement`:
+
+- `product_detail`
+- `floating`
+- `header`
+- `footer`
+- `contact_page`
+- `checkout`
+- `other` únicamente cuando ninguna ubicación canónica describe el contacto
+
+El campo es opcional, no acepta textos visibles ni valores libres y el runtime
+lo ignora cuando el evento no es `contact`. Una ubicación nueva debe añadirse
+primero al contrato oficial del SDK.
+
+Un contacto asociado a un producto debe incluir la variante, cantidad y valor:
+
+```tsx
+marketing.track({
+  eventName: "contact",
+  contactMethod: "whatsapp",
+  contactPlacement: "product_detail",
+  value: unitPrice * quantity,
+  items: [
+    {
+      itemId: selectedVariant.id,
+      itemName: product.name,
+      sku: selectedVariant.sku,
+      price: unitPrice,
+      quantity,
+      itemBrand: product.brand?.name,
+      itemCategory: product.category,
+      itemVariant: variantLabel,
+    },
+  ],
+});
+```
+
+Un botón flotante o enlace general no debe atribuirse artificialmente a un
+producto. GA4 recibe `method`, `contact_placement`, `items` y `value`; Meta
+recibe el evento estándar `Contact`, `contact_method`, `contact_placement`,
+`content_ids` y `contents` cuando existen items.
+
+Clarity registra automáticamente el comportamiento visual de la sesión y
+recibe `contact` como evento personalizado para filtrar grabaciones. No recibe
+PII, items ni etiquetas construidas por el storefront. La guía específica está
+en [`STOREFRONT_CLARITY.md`](./STOREFRONT_CLARITY.md).
+
+## Fuente única y deduplicación
+
+- Cada interacción tiene un único propietario de instrumentación.
+- No se combinan handlers locales con seguimiento automático duplicado.
+- `page_view` tiene una sola fuente para navegación inicial y SPA.
+- Un cambio de cantidad puede expresarse como diferencia real de carrito; no se
+  vuelve a emitir todo el carrito como nuevas altas.
+- Los efectos de React deben depender de identidades primitivas estables o
+  contar con una guarda explícita para evitar duplicados.
+
+## URLs, atribución y privacidad
+
+- No enviar URLs construidas manualmente; el runtime usa y sanea la ubicación
+  actual cuando `pageLocation` se omite.
+- Nunca incluir email, teléfono, dirección, documento, tokens de pedido,
+  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
+  las reglas de autorización de Bacano.
+
+## Componentes que todo storefront debe auditar
+
+- Provider raíz y una única fuente de `page_view`.
+- Buscador, resultados, categorías, colecciones y tarjetas de producto.
+- Detalle, selección de variante y recomendaciones si están dentro del alcance.
+- Carrito: alta, baja, cantidad y vista.
+- Checkout: inicio, entrega, pago y consentimiento.
+- Todos los enlaces de WhatsApp, teléfono y correo.
+- Preview: marketing desactivado en todo su árbol.
+
+## Content Security Policy
+
+La CSP pertenece al storefront y se genera durante el build o en el hosting.
+El runtime no puede ampliar una cabecera que el navegador ya recibió. Se deben
+incluir únicamente los proveedores activos del website y conservar los demás
+orígenes que realmente use la aplicación.
+
+Para GA4 y destinos de Google Ads vinculados al mismo Google tag:
+
+```text
+script-src  https://www.googletagmanager.com
+connect-src https://www.googletagmanager.com
+            https://www.google-analytics.com
+            https://*.google-analytics.com
+            https://analytics.google.com
+            https://*.analytics.google.com
+            https://stats.g.doubleclick.net
+            https://googleads.g.doubleclick.net
+            https://www.googleadservices.com
+img-src     https://www.google-analytics.com
+            https://googleads.g.doubleclick.net
+            https://www.googleadservices.com
+```
+
+`https://www.googletagmanager.com` debe estar tanto en `script-src` como en
+`connect-src`: Google tag puede usar `/td` mediante `fetch`, aunque el script
+principal ya haya cargado correctamente.
+
+Para Meta Pixel:
+
+```text
+script-src  https://connect.facebook.net
+connect-src https://www.facebook.com https://graph.facebook.com
+img-src     https://www.facebook.com
+frame-src   https://www.facebook.com
+form-action 'self' https://www.facebook.com
+```
+
+Meta puede enviar `/tr/` mediante un formulario POST dirigido a un iframe
+oculto. Permitir `connect-src` o `img-src` no sustituye `form-action` y
+`frame-src`. Usar el origen exacto; no abrir `*.facebook.com` ni comodines de
+infraestructura para silenciar errores.
+
+Para Microsoft Clarity:
+
+```text
+script-src  https://*.clarity.ms
+connect-src https://*.clarity.ms https://c.bing.com
+img-src     https://*.clarity.ms https://c.bing.com
+```
+
+Clerk, Wompi, videos y cualquier otro proveedor conservan su propia lista de
+orígenes. La CSP final es la unión mínima de las capacidades efectivamente
+montadas. Probarla en consola, Network y, cuando sea posible, primero mediante
+`Content-Security-Policy-Report-Only`.
+
+## Validación obligatoria
+
+Antes de declarar un storefront listo:
+
+1. Ejecutar typecheck, lint, unit tests y build.
+2. Probar que acciones fallidas no emitan eventos exitosos.
+3. Confirmar que una acción produzca un solo evento.
+4. Verificar IDs, variantes, cantidades, valores y moneda.
+5. Revisar URLs para confirmar que no contienen tokens ni PII.
+6. Validar GA4 en DebugView o tiempo real.
+7. Validar Meta en Test Events y revisar `content_ids`.
+8. Confirmar que preview y localhost no envíen eventos reales.
+9. Si existe catálogo publicitario, confirmar que cada `itemId` coincide con el
+   `id` de la misma variante en la fuente de Meta o Google.
+10. Si Clarity está activo, validar tag, recolección, sesiones y eventos
+    personalizados en el dominio canónico.
+11. Confirmar que la CSP no bloquea los transportes reales de GA4, Meta o
+    Clarity, incluidos Google tag `/td` y Meta `/tr/` por POST/iframe.
+
+## Checklist corto para agentes
+
+- [ ] Leí este contrato antes de instrumentar.
+- [ ] Uso únicamente `useMarketing().track()`.
+- [ ] Uso `product_variant_id` como `itemId`.
+- [ ] Emito eventos después del éxito, no antes.
+- [ ] Instrumenté todos los contactos con método y ubicación.
+- [ ] Los contactos de producto incluyen item, cantidad y valor.
+- [ ] No emito conversiones autoritativas desde el navegador.
+- [ ] No envío PII, tokens o secretos.
+- [ ] No duplico `page_view` ni eventos por renders.
+- [ ] Validé GA4, Meta, Clarity, preview y degradación segura.
+
+La guía de gobierno, persistencia y eventos autoritativos vive en
+`docs/websites/MARKETING_MEASUREMENT_STOREFRONTS_CHECKLIST.md` dentro del
+repositorio Bacano. Este archivo es el contrato distribuible para storefronts.

package/STOREFRONT_PERFORMANCE.md

@@ -0,0 +1,304 @@
+# Storefront performance contract
+
+This is the canonical performance contract for storefronts built with
+`@bacano/sdk`. It applies to static, hybrid and server-rendered storefronts.
+
+## Required architecture
+
+1. Create one `BacanoClient` and mount one `BacanoProvider` at the application
+   root. Do not create independent clients per component or route.
+2. Generate catalog routes and their page data from one build snapshot. Never
+   call `getProductBySlug()` once for every product during the same build.
+3. Render useful catalog and product HTML during the static/server render.
+   Loading skeletons are fallbacks, not the initial production document.
+4. Use the SDK for every Bacano request. Storefronts must not duplicate GraphQL
+   documents, gateway limits, retries or storage transform rules.
+5. Keep build data separate from volatile state. Prices and availability may be
+   refreshed after hydration with the lightweight live-state contract.
+6. A live refresh must preserve the static content when it fails. A public page
+   must not become empty because Bacano is temporarily unavailable.
+
+## Static catalog bootstrap
+
+Use one bootstrap per website build:
+
+```ts
+const bootstrap = await client.catalog.getStaticCatalogBootstrap({
+  categoryListKey: "categorias-web",
+  attributeListKey: "atributos",
+  pageSize: 100,
+  initialPageSize: 24,
+  maxProducts: 10_000,
+  sortBy: "name_asc",
+});
+
+// Render this in the initial catalog HTML.
+const initialCatalogPage = bootstrap.initialPage;
+
+// Reuse the same objects for routes, metadata, JSON-LD and sitemap.
+const productByRoute = new Map(
+  bootstrap.products.map((product) => [product.slug || product.id, product]),
+);
+```
+
+The SDK paginates internally, respects `Retry-After`, rejects inconsistent
+snapshots and avoids repeating facets on every page. Builds must fail clearly
+if this contract fails; they must not silently publish an empty catalog.
+
+### Listing variants and detail variants
+
+The static bootstrap deliberately exposes two projections on each product:
+
+- `product.variants` contains only variants that were saleable when Bacano
+  generated the catalog page. Cards, price ranges, filters and listing
+  visibility must use this projection.
+- `product.detailVariants` also contains enabled, published variants with a
+  public price that are currently sold out. Product detail selectors must use
+  this projection so a customer can see unavailable sizes instead of assuming
+  they do not exist.
+
+Use the public helper so cached snapshots from older SDK versions remain safe:
+
+```ts
+import { getProductDetailVariants } from "@bacano/sdk";
+
+const detailVariants = getProductDetailVariants(product);
+const liveState = await client.catalog.getProductLiveState(
+  detailVariants.map((variant) => variant.id),
+);
+```
+
+`getProduct()` and `getProductBySlug()` expose the complete detail projection
+through `variants` as well. A sold-out variant returns `inStock: false` and
+`maxPurchasableQuantity: 0` from live state. Never use `detailVariants` to
+calculate a card's minimum price or to make a completely sold-out product
+appear in listings.
+
+## Live price and availability
+
+After hydration, refresh only the variants visible on screen:
+
+```ts
+const liveState = await client.catalog.getProductLiveState(visibleVariantIds);
+```
+
+One call accepts at most 100 unique variant IDs. Debounce filter/pagination
+changes and do not refresh the whole static catalog. The response only contains
+variant ID, current pricing, availability and `maxPurchasableQuantity`.
+
+For a local cart, batch all distinct variant IDs when the cart opens and use
+`maxPurchasableQuantity` as the total cap per variant, including units already
+in the cart. Disable quantity increases at the cap and explain that the maximum
+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
+with a realistic `sizes` value so mobile devices do not download desktop media:
+
+```tsx
+import { formatMediaSrcSet } from "@bacano/sdk";
+
+<img
+  src={media.cardUrl || media.url}
+  srcSet={formatMediaSrcSet(media.responsiveSources ?? []) || undefined}
+  sizes="(max-width: 640px) 50vw, (max-width: 1200px) 33vw, 320px"
+  width={320}
+  height={400}
+  loading="lazy"
+  decoding="async"
+  alt={media.altText || product.name}
+/>;
+```
+
+The first visible product image may use eager loading/high priority. Images
+below the fold and recommendation blocks must remain lazy. Storefronts must not
+append storage transformation query parameters manually.
+
+### Banners and full-width heroes
+
+Editorial `ContentMedia` images additionally expose:
+
+```ts
+type ContentMedia = {
+  src?: string | null;
+  url?: string | null;
+  originalUrl?: string | null;
+  thumbnailUrl?: string | null;
+  cardUrl?: string | null;
+  detailUrl?: string | null;
+  heroUrl?: string | null;
+  responsiveSources?: Array<{ width: number; url: string }>;
+  originalWidth?: number | null;
+  originalHeight?: number | null;
+};
+```
+
+`src` and `url` remain available as compatibility aliases. New storefront code
+must select the semantic URL that matches its rendering context.
+
+`heroUrl` is an optimized WebP fallback for wide editorial media. Bacano uses
+the candidates `640`, `960`, `1400`, `1920` and `2560`, but removes every size
+larger than the original file and adds the exact intrinsic width as the final
+candidate. A 1920 px source therefore ends at 1920 px; a 1180 px source ends at
+1180 px. When Bacano cannot determine the dimensions, `heroUrl` safely falls
+back to `originalUrl` and no speculative `srcset` is emitted.
+
+For separate mobile and desktop artwork, keep the breakpoint in the storefront
+and let the browser choose density within each source:
+
+```tsx
+import { formatMediaSrcSet, type ContentMedia } from "@bacano/sdk";
+
+export function EditorialHero({
+  desktop,
+  mobile,
+}: {
+  desktop: ContentMedia;
+  mobile: ContentMedia;
+}) {
+  return (
+    <picture>
+      <source
+        media="(max-width: 767px)"
+        srcSet={formatMediaSrcSet(mobile.responsiveSources ?? []) || undefined}
+        sizes="100vw"
+      />
+      <img
+        src={desktop.heroUrl ?? desktop.originalUrl ?? ""}
+        srcSet={formatMediaSrcSet(desktop.responsiveSources ?? []) || undefined}
+        sizes="100vw"
+        width={desktop.originalWidth ?? undefined}
+        height={desktop.originalHeight ?? undefined}
+        alt={desktop.alt ?? ""}
+        decoding="async"
+      />
+    </picture>
+  );
+}
+```
+
+This contract works in static exports: all URLs are deterministic, cacheable
+gateway URLs and the browser selects the appropriate candidate at runtime for
+device-pixel ratios 1 and 2. Do not use `detailUrl` as the fallback for a
+full-width hero and do not append `w`, `q` or `f` parameters in a storefront.
+
+## Request ownership
+
+- Website initialization: obtain one public configuration and use it to seed the
+  SDK context. Do not resolve the same website again through GraphQL.
+- Catalog build: one paginated bootstrap.
+- Initial catalog navigation: zero mandatory catalog requests after hydration;
+  the static page is already usable.
+- Live state: one batched request for visible variants.
+- Recommendations: load independently and lazily; they must not delay product
+  title, price, selected variant or primary media.
+- Shipping policy and public configuration: read once in the root data layer and
+  share the result.
+
+### Shared website bootstrap
+
+The public configuration is the canonical bootstrap shared by buyer accounts,
+marketing and the SDK client. A static or server-rendered storefront should
+fetch it once, cache it for the build/render window and pass its context into
+the root provider:
+
+```tsx
+import {
+  getWebsiteContextFromPublicConfig,
+  getWebsitePublicConfig,
+} from "@bacano/sdk";
+import { BacanoMarketingProvider, BacanoProvider } from "@bacano/sdk/react";
+
+const publicConfig = await getWebsitePublicConfig({
+  apiUrl,
+  websiteSlug,
+  origin: canonicalOrigin,
+});
+
+<BacanoProvider
+  config={{
+    apiUrl,
+    websiteSlug,
+    initialContext: getWebsiteContextFromPublicConfig(publicConfig),
+  }}
+>
+  <BacanoMarketingProvider
+    publicConfig={publicConfig}
+    scriptLoadStrategy="idle"
+  >
+    {children}
+  </BacanoMarketingProvider>
+</BacanoProvider>;
+```
+
+`scriptLoadStrategy="idle"` prepares the GA4, Meta, and Clarity command queues
+immediately, so events are not lost, but postpones downloading their vendor
+scripts until browser idle time or the first interaction. The default remains
+`"immediate"` for backward compatibility.
+
+If the storefront refreshes public configuration in the browser, it must keep
+the static bootstrap while the refresh is pending and only replace it when the
+payload actually changes. Configuration failure must not blank the storefront.
+
+Mount third-party authentication only on routes that require it, such as
+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.
+- [ ] Routes, sitemap, metadata and JSON-LD reuse the same build bootstrap.
+- [ ] No direct GraphQL and no per-product build fetch loop.
+- [ ] One `BacanoProvider` and no duplicated website/config requests.
+- [ ] The provider receives `initialContext` from the shared public config.
+- [ ] Marketing commands queue before scripts and idle loading loses no events.
+- [ ] Authentication vendor scripts are absent from public catalog routes.
+- [ ] `srcset` and `sizes` are present on catalog and product media.
+- [ ] Live refresh is batched, debounced and failure-safe.
+- [ ] Recommendations and below-fold media do not block the primary content.
+- [ ] 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.