@bacano/sdk 1.0.0 → 1.1.0

package/STOREFRONT_LEADS.md

@@ -0,0 +1,130 @@
+# Captura de leads en storefronts Bacano
+
+Este es el contrato canónico para formularios comerciales construidos por un
+storefront. Bacano no impone un constructor visual: cada tienda decide sus
+campos y diseño, pero toda captura debe entrar por `@bacano/sdk`.
+
+## Responsabilidades
+
+El storefront:
+
+- Renderiza el formulario y valida su experiencia básica.
+- Muestra exactamente `publicConfig.legal.directMarketingConsent.statement`.
+- Mantiene la aceptación opcional desmarcada hasta una acción explícita.
+- Genera una clave de idempotencia por envío y la conserva durante reintentos.
+- Envía únicamente respuestas necesarias para el propósito informado.
+
+Bacano:
+
+- Deriva y valida el website y su dominio.
+- Resuelve la campaña por su clave pública.
+- Conserva la versión y huella del texto aceptado.
+- Reutiliza la identidad, el lead o el cliente existente sin duplicarlos.
+- Completa un correo o teléfono faltante únicamente cuando la coincidencia de
+  identidad es inequívoca; nunca reemplaza un dato existente.
+- Conserva el contacto enviado dentro de la evidencia de autorización ligada a
+  la captura, incluso cuando el participante ya era cliente.
+- Conserva la captura, atribución y respuestas como evidencia inmutable.
+- Aplica límites de frecuencia, tamaño e idempotencia.
+
+## Configuración previa
+
+1. Configura el texto de **Autorización de comunicaciones comerciales** en la
+   pestaña Legal del website.
+2. Crea una campaña en Bacano y actívala.
+3. Usa su clave pública estable en el formulario.
+
+Una campaña en borrador, pausada, finalizada, fuera de vigencia o asociada a
+otro website no acepta capturas. Si el texto legal no existe, el storefront no
+debe mostrar ni habilitar el formulario comercial.
+
+## Implementación
+
+```tsx
+const consent = publicConfig.legal.directMarketingConsent;
+
+if (!consent) return null;
+
+// Renderiza consent.statement junto a un checkbox desmarcado.
+// Ejecuta esta llamada únicamente después de validar el formulario y aceptar.
+// Conserva esta clave en el estado del formulario mientras reintentas el envío.
+const idempotencyKey = crypto.randomUUID();
+const result = await client.marketing.captureLead({
+  campaignKey: "newsletter-baby-rex",
+  idempotencyKey,
+  commercialConsent: true,
+  contact: {
+    partyKind: "PERSON",
+    firstName: "Ana",
+    email: "ana@example.com",
+  },
+  answers: {
+    interest: "bebe-nina",
+  },
+});
+```
+
+Debe existir al menos correo o teléfono. Los nombres son opcionales. Para una
+empresa pueden usarse `partyKind: "COMPANY"`, `legalName` y `commercialName`.
+
+`source` se omite para formularios normales y será `WEBSITE`. Usa `QR`
+únicamente cuando el formulario se abrió mediante una entrada QR controlada por
+el storefront. UTM, referidor y click IDs se toman automáticamente de la
+atribución segura del SDK.
+
+El storefront no debe construir ni enviar manualmente el payload HTTP. El SDK
+serializa este contrato como JSON y la ruta pública de Bacano lo procesa antes
+de validar la campaña. Un SDK `1.0.14` o posterior conserva esta forma del
+payload; no se requieren adaptadores específicos por tienda.
+
+## Respuestas personalizadas
+
+`answers` es un snapshot del formulario, no un constructor de campos del CRM.
+
+- Máximo 50 claves, cada una de hasta 80 caracteres.
+- Payload total aproximado máximo: 30 KB.
+- No incluyas contraseñas, tokens, datos de pago, documentos adjuntos ni HTML.
+- No dupliques correo o teléfono dentro de `answers`; usa `contact`.
+- Un cambio futuro del formulario no modifica capturas anteriores.
+
+## Idempotencia y privacidad
+
+- La misma interacción debe reutilizar el mismo `idempotencyKey` hasta obtener
+  respuesta. Un nuevo envío voluntario usa una clave nueva.
+- La respuesta es deliberadamente genérica y nunca revela si la persona ya era
+  lead o cliente.
+- Si correo y teléfono pertenecen a identidades activas diferentes, Bacano no
+  sobrescribe ninguna de ellas y conserva el caso para revisión manual.
+- No llames GraphQL, Hasura ni endpoints internos directamente.
+- No captures un lead si el visitante no aceptó el texto comercial vigente.
+- Una revocación posterior conserva el historial, pero impide comunicaciones
+  futuras hasta una nueva aceptación expresa.
+
+## Beneficio de primera compra
+
+Cuando la campaña activa tiene objetivo `FIRST_PURCHASE_COUPON` y referencia un
+cupón online vigente, Bacano puede encolar el correo de bienvenida después de
+aceptar la captura. Esta operación es completamente del servidor:
+
+- el storefront no envía correos ni consulta Resend;
+- no debe afirmar que el cupón ya fue enviado;
+- repetir la misma captura no duplica el beneficio;
+- una falla de correo nunca convierte la captura en error;
+- Bacano revalida autorización, campaña, website, cupón y compras anteriores
+  inmediatamente antes del envío.
+
+El contrato de `captureLead()` no cambia y no expone estados internos del
+correo. La evidencia operativa queda en `outbound_emails` dentro de Bacano. El
+newsletter masivo y las automatizaciones visuales continúan fuera de alcance.
+
+## Checklist para agentes
+
+- [ ] Leí este contrato antes de crear el formulario.
+- [ ] Uso un único `BacanoClient` inicializado.
+- [ ] Leo el texto desde `publicConfig.legal.directMarketingConsent`.
+- [ ] La aceptación empieza desmarcada y es explícita.
+- [ ] Uso `client.marketing.captureLead()` y no GraphQL directo.
+- [ ] Conservo la clave de idempotencia durante reintentos.
+- [ ] No envío secretos ni información innecesaria en `answers`.
+- [ ] No afirmo que el correo o el cupón fueron entregados a partir de la
+      respuesta genérica de `captureLead()`.

package/STOREFRONT_LEGAL.md

@@ -0,0 +1,66 @@
+# Storefront legal settings
+
+This document is the canonical contract for legal content exposed by the
+Bacano SDK. Storefronts must use this configuration instead of maintaining
+parallel legal documents in Content or querying GraphQL directly.
+
+## Public contract
+
+`getWebsitePublicConfig()` returns the current configuration for the resolved
+website:
+
+```ts
+const config = await getWebsitePublicConfig(options);
+
+config.legal = {
+  schemaVersion: 1,
+  version: 3,
+  contentHash: "...",
+  documents: {
+    terms: { type: "doc", content: [] },
+    shipping: { type: "doc", content: [] },
+    returns: { type: "doc", content: [] },
+    privacy: { type: "doc", content: [] },
+    cookies: { type: "doc", content: [] },
+  },
+  inquiriesChannel: "privacidad@example.com",
+  cookieNotice: {
+    enabled: true,
+    message: "Usamos cookies propias y de terceros...",
+    buttonLabel: "Entendido",
+  },
+};
+```
+
+All documents and the inquiries channel are optional. Missing documents are
+returned as `null`. Documents use Bacano's rich-text JSON format and must be
+rendered safely; do not inject untrusted HTML.
+
+The configuration is included in the existing public-config request. Do not
+add a second request, direct GraphQL access, or local fallback copies of legal
+text.
+
+## Informational cookie notice
+
+Render the notice only when `config.legal.cookieNotice.enabled` is `true`.
+Display the message and button label supplied by Bacano, allow the visitor to
+close it, and store that dismissal locally if the storefront should avoid
+showing it again in the same browser.
+
+The notice is informational. It is not a consent manager and does not gate,
+delay, or reconfigure the GA4, Meta, or Microsoft Clarity runtime. Marketing remains governed by
+`config.marketing`.
+
+## Storefront checklist
+
+- Preserve existing public legal routes and their SEO behavior.
+- Source terms, shipping, returns, privacy, cookies, and the contact channel only from
+  `config.legal`.
+- Handle every nullable document without crashing or inventing content.
+- Remove only the obsolete legal Content keys; keep unrelated Content data.
+- Do not add direct GraphQL calls or duplicate public-config requests.
+- Verify the notice in enabled, disabled, and dismissed states.
+- Verify GA4, Meta, and Clarity continue operating in every notice state.
+- Do not present the informational notice as consent for Clarity. Review the
+  privacy rules in `STOREFRONT_CLARITY.md` before activating it.
+- Run typecheck, lint, unit tests, E2E tests, and the production build.

package/STOREFRONT_MARKETING.md

@@ -0,0 +1,286 @@
+# 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.
+- 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.