@bacano/sdk 1.0.1 → 1.1.0

package/README.md

@@ -21,13 +21,118 @@ 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.
+
+#### 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`.
+
 ### 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.
 
 ---
 
@@ -148,6 +253,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({
@@ -211,9 +353,18 @@ 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. 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.
+
 ### 4. Local Cart And Checkout Start
 
 The website checkout remains guest-first. Buyer credentials and email
@@ -337,6 +488,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
@@ -624,6 +789,166 @@ configured identity provider owns their lifecycle.
 
 ## 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.
+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`:
@@ -1223,6 +1548,7 @@ The SDK throws typed errors you can catch and handle:
 ```typescript
 import {
   WebsiteError,
+  RateLimitError,
   AuthError,
   CheckoutError,
   NotInitializedError,
@@ -1248,6 +1574,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 +1585,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 +1629,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 +1637,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,

package/STOREFRONT_CLARITY.md

@@ -0,0 +1,140 @@
+# Microsoft Clarity en storefronts Bacano
+
+Este documento define la integración oficial de Microsoft Clarity para todos
+los storefronts que usan `@bacano/sdk`. Clarity aporta mapas de calor,
+grabaciones de sesión y análisis de comportamiento; no reemplaza GA4, Meta ni
+los eventos comerciales autoritativos de Bacano.
+
+## Responsabilidades
+
+El comercio crea y administra su proyecto en Microsoft Clarity. Se recomienda
+un proyecto diferente por dominio. En Bacano, dentro de **Sitios web > Marketing
+y medición > Microsoft Clarity**, registra el `Project ID`, guarda, prueba la
+conexión y la activa.
+
+El `Project ID` es público. Bacano lo guarda por `website_id`; no existe un
+secreto de servidor para esta integración. El SDK solo lo recibe cuando la
+integración está activa, validada y la petición corresponde al dominio canónico
+de producción.
+
+El storefront es responsable únicamente de:
+
+1. Usar una versión del SDK que incluya este contrato.
+2. Montar una sola vez el `BacanoMarketingProvider` existente.
+3. Seguir emitiendo los eventos canónicos mediante `useMarketing().track()`.
+
+No debe instalar otro paquete de Clarity, copiar el snippet de Microsoft,
+consultar GraphQL ni construir una segunda petición de configuración.
+
+```tsx
+import { getWebsitePublicConfig } from "@bacano/sdk";
+import { BacanoMarketingProvider } from "@bacano/sdk/react";
+
+const publicConfig = await getWebsitePublicConfig({ apiUrl, websiteSlug });
+
+<BacanoMarketingProvider publicConfig={publicConfig} scriptLoadStrategy="idle">
+  <Storefront />
+</BacanoMarketingProvider>;
+```
+
+Cuando Clarity está activo, el provider carga una sola vez
+`https://www.clarity.ms/tag/{projectId}`. En localhost, preview y dominios no
+canónicos se mantiene como `no-op`.
+
+Si el storefront aplica una Content Security Policy, debe permitir los
+endpoints oficiales de Clarity (`https://*.clarity.ms` y
+`https://c.bing.com`) en las directivas correspondientes de scripts y
+conexiones. Conviene probar primero la política en modo report-only y revisar
+la consola del navegador antes de aplicarla.
+
+La matriz distribuible de CSP para Clarity, GA4 y Meta vive únicamente en
+[`STOREFRONT_MARKETING.md`](./STOREFRONT_MARKETING.md). No mantener una segunda
+lista dentro del storefront: componer desde allí solo los proveedores activos
+y añadir por separado los orígenes propios de autenticación, pagos o video.
+
+Las imágenes y videos públicos entregados por
+`/storage/v1/files/{fileId}` aceptan lectura credentialless desde renderizadores
+externos. Bacano valida que el archivo pertenezca a media pública de una empresa
+con un storefront activo antes de servirlo y mantiene privados los archivos no
+elegibles. El storefront no debe crear un proxy, reenviar cookies ni modificar
+las URLs de media para que aparezcan en las reproducciones de Clarity.
+
+Una política CSP solo puede componerse con datos conocidos durante el build.
+El runtime no intenta modificar una cabecera CSP después de cargar la página.
+Si un proveedor incorpora un origen dinámico no documentado —por ejemplo, un
+endpoint auxiliar de Meta alojado en infraestructura cloud— no se deben abrir
+comodines amplios como `*.on.aws` o `*.run.app`. Ese origen debe validarse y
+declararse de manera exacta en el hosting hasta que el proveedor ofrezca un
+contrato estable que Bacano pueda publicar de forma segura.
+
+## Eventos y alcance
+
+Clarity captura automáticamente navegación, clics, desplazamiento, errores y
+la representación necesaria para sus mapas y grabaciones. Adicionalmente, el
+SDK reenvía cada evento canónico de navegador como un evento personalizado de
+Clarity con el mismo nombre, por ejemplo:
+
+- `view_item`
+- `add_to_cart`
+- `begin_checkout`
+- `contact`
+
+Esto permite filtrar grabaciones y mapas por pasos del embudo sin instrumentar
+handlers paralelos. El storefront no debe llamar a `window.clarity()`.
+
+Clarity es un destino exclusivo de navegador. `order_placed`, `purchase` y
+`refund` continúan enviándose de forma autoritativa a GA4 y Meta desde Bacano;
+no se crea un outbox de servidor para Clarity.
+
+## Privacidad y seguridad
+
+- No enviar email, teléfono, documento, dirección, tokens ni otros datos
+  personales a eventos o etiquetas de Clarity.
+- Clarity enmascara por defecto entradas, números y correos. Los storefronts
+  deben añadir `data-clarity-mask` a cualquier zona personalizada sensible que
+  requiera protección adicional.
+- No usar `data-clarity-unmask` en checkout, cuenta, autenticación o formularios
+  con datos personales.
+- Microsoft indica que Clarity no debe utilizarse en sitios o aplicaciones
+  dirigidos a menores de 18 años. El comercio debe evaluar su audiencia antes
+  de activarlo.
+- El aviso informativo de cookies de Bacano no es un gestor de consentimiento.
+  Si un comercio opera en una jurisdicción que exige consentimiento previo,
+  debe implementar un mecanismo de consentimiento válido antes de activar la
+  recolección completa.
+
+No se utiliza la API `identify`: Bacano no entrega a Clarity identidades de
+clientes ni compradores.
+
+## Verificación
+
+Después de desplegar el storefront en su dominio canónico:
+
+1. Abrir el sitio sin modo preview.
+2. Confirmar en la pestaña Network la carga de `clarity.ms/tag/{projectId}` y
+   solicitudes de recolección a Clarity.
+3. Navegar, abrir un producto y agregarlo al carrito.
+4. Revisar sesiones en tiempo real, mapas y eventos personalizados dentro del
+   proyecto correcto de Clarity.
+5. Abrir una reproducción y confirmar que las imágenes públicas de productos y
+   Content cargan desde `api.bacanoerp.com/storage/v1/files/`.
+6. Confirmar que localhost, preview y otro dominio no envíen datos.
+7. Confirmar que una falla o bloqueo del script no afecte catálogo, carrito o
+   checkout.
+
+Microsoft puede tardar algunos minutos en mostrar la primera información. Una
+prueba válida en Bacano confirma el Project ID y la disponibilidad del tag; no
+demuestra que un navegador concreto esté libre de bloqueadores.
+
+## Checklist para agentes de storefront
+
+- [ ] Uso un único `BacanoMarketingProvider`.
+- [ ] No instalé el snippet ni un paquete paralelo de Clarity.
+- [ ] Los eventos continúan saliendo solo de `useMarketing().track()`.
+- [ ] Preview y localhost no cargan Clarity.
+- [ ] Las zonas sensibles permanecen enmascaradas.
+- [ ] No uso `identify`, PII ni etiquetas con datos personales.
+- [ ] Las imágenes públicas se reconstruyen sin un proxy del storefront.
+- [ ] Validé carga, recolección, sesiones y eventos en producción.
+
+El contrato general de eventos permanece en `STOREFRONT_MARKETING.md`.

package/STOREFRONT_CONSTRUCTION.md

@@ -0,0 +1,92 @@
+# Sitio en construcción para storefronts Bacano
+
+Este documento define el contrato oficial para ocultar temporalmente un sitio
+Bacano sin reconstruir su export estático. Aplica a SiteGround y otros hostings
+estáticos; una futura integración con CloudFront podrá aplicar la misma
+configuración en el edge.
+
+## Responsabilidades
+
+- Bacano conserva la configuración por `website_id`, valida las imágenes y
+  entrega únicamente datos públicos.
+- `public-config` decide si la pantalla debe aplicarse. Localhost, desarrollo y
+  orígenes no canónicos nunca quedan bloqueados.
+- El SDK administra la consulta en vivo, la pantalla responsive y el acceso
+  temporal de vista previa.
+- El storefront solo monta `BacanoWebsiteGate`. No consulta GraphQL, no lee
+  `websites.config` y no construye URLs de Storage.
+
+## Integración React
+
+El gate debe envolver autenticación, marketing y la aplicación. De esta forma
+Clerk, GA4, Meta y Clarity no se cargan mientras la pantalla esté activa.
+
+```tsx
+"use client";
+
+import { BacanoWebsiteGate } from "@bacano/sdk/react";
+
+export function WebsiteVisibility({ children }: { children: React.ReactNode }) {
+  return (
+    <BacanoWebsiteGate
+      config={{
+        apiUrl: process.env.NEXT_PUBLIC_BACANO_API_URL!,
+        websiteSlug: process.env.NEXT_PUBLIC_BACANO_WEBSITE_SLUG!,
+      }}
+    >
+      {children}
+    </BacanoWebsiteGate>
+  );
+}
+```
+
+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.
+
+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`.
+
+## Vista previa temporal
+
+Desde Bacano, un usuario con `websites.manage` puede generar un enlace válido
+durante dos horas:
+
+```text
+https://tienda.example/#bacano-preview=<token-firmado>
+```
+
+El fragmento no viaja al hosting ni se incluye en el `Referer`. El gate lo
+guarda en `sessionStorage`, limpia la barra de direcciones y valida el token
+contra `public-config`. La vista previa termina al cerrar esa sesión, al vencer
+el token o al borrar los datos del navegador.
+
+No convertir el token en query string, cookie permanente ni variable de build.
+
+## Seguridad y límites de hosting estático
+
+En SiteGround esta es una barrera de presentación ejecutada por JavaScript. No
+impide descargar el HTML estático ni devuelve HTTP 503, por lo que no debe
+usarse como control de acceso para información sensible. El contenido privado
+nunca debe formar parte del export público. Mientras la pantalla está activa,
+el gate añade `noindex,nofollow`; en un hosting estático esto sigue dependiendo
+de que el crawler ejecute JavaScript.
+
+Cuando Bacano opere el storefront en CloudFront, la misma bandera podrá
+resolverse antes de servir la página, devolver 503 y aplicar `noindex` desde el
+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.
+- 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`.
+- Un fallo de `public-config` degrada de forma abierta y no tumba el sitio.