@bacano/sdk 1.0.1 → 1.1.8

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,105 @@
+# 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.
+
+Mientras confirma la configuración, el gate serializa `children` dentro de un
+`<noscript>` semántico. El catálogo, los productos, encabezados y enlaces siguen
+presentes en el HTML exportado y son visibles cuando JavaScript está
+deshabilitado, pero React no monta esos descendientes. Así evita cargar Clerk,
+GA4, Meta o Clarity y tampoco muestra fugazmente la tienda si construcción está
+activa. `loadingFallback` es únicamente la UI visible para navegadores con
+JavaScript durante esa consulta; por defecto permanece vacío.
+
+La pantalla oficial usa la imagen mobile hasta 767 px y la desktop desde 768
+px. En ambos casos emplea las fuentes responsivas generadas por Bacano. Si solo
+existe una de las dos imágenes la reutiliza de forma segura; si no existe
+ninguna, conserva el fondo y muestra el título y mensaje configurados. El
+storefront puede proporcionar `constructionFallback` si requiere una UI propia,
+pero no debe alterar la decisión `construction.enforced`.
+
+## Vista previa temporal
+
+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.
+- El export contiene el catálogo estático dentro del fallback `<noscript>`.
+- Sin JavaScript, catálogo, productos y enlaces continúan visibles.
+- La configuración se consulta en runtime con `cache: no-store`.
+- La pantalla activa no inicializa Clerk, GA4, Meta ni Clarity.
+- Localhost y dominios de desarrollo siguen mostrando la web.
+- Las imágenes desktop y mobile usan `srcset` y `sizes`.
+- El enlace temporal abre el storefront y desaparece de la barra de dirección.
+- Un token vencido no concede acceso y se elimina de `sessionStorage`.
+- La pantalla oficial sigue siendo útil aunque no tenga imágenes.
+- Un fallo de `public-config` degrada de forma abierta y no tumba el sitio.

package/STOREFRONT_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.