@bacano/sdk 1.1.15 → 1.1.18

package/react.js

@@ -12,10 +12,10 @@ var WebsiteError = class extends Error {
   }
 };
 var RateLimitError = class extends WebsiteError {
-  constructor(message, retryAfterSeconds) {
+  constructor(message, retryAfterSeconds2) {
     super(message, "RATE_LIMITED", {
       status: 429,
-      retryAfterSeconds
+      retryAfterSeconds: retryAfterSeconds2
     });
     this.name = "RateLimitError";
   }
@@ -6445,6 +6445,171 @@ function createContentModule(graphqlUrl, getHeaders, getContext, storageUrl) {
   };
 }
 
+// libs/sdk/src/modules/forms.ts
+function retryAfterSeconds(response) {
+  const value = Number(response.headers.get("Retry-After") ?? "1");
+  return Number.isFinite(value) && value >= 0 ? Math.ceil(value) : 1;
+}
+function isFormKey(value) {
+  return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+}
+function createFormsModule(apiUrl, websiteSlug, getContext) {
+  const cache = /* @__PURE__ */ new Map();
+  function getServerOrigin() {
+    if (typeof window !== "undefined") return null;
+    const domain = getContext().domain?.trim();
+    if (!domain) return null;
+    try {
+      return new URL(domain.includes("://") ? domain : `https://${domain}`).origin;
+    } catch {
+      return null;
+    }
+  }
+  return {
+    async getDefinition(formKey, options) {
+      const normalizedKey = formKey.trim();
+      if (!isFormKey(normalizedKey)) {
+        throw new WebsiteError(
+          "formKey has an invalid format",
+          "INVALID_FORM_KEY"
+        );
+      }
+      const cached = cache.get(normalizedKey);
+      if (!options?.force && cached && cached.expiresAt > Date.now()) {
+        return cached.value;
+      }
+      const url = new URL(
+        `${apiUrl.replace(/\/+$/, "")}/api/v1/website/forms/definition`
+      );
+      url.searchParams.set("websiteSlug", websiteSlug);
+      url.searchParams.set("formKey", normalizedKey);
+      let response;
+      try {
+        const serverOrigin = getServerOrigin();
+        const headers = new Headers();
+        if (serverOrigin) headers.set("Origin", serverOrigin);
+        if (cached?.etag) headers.set("If-None-Match", cached.etag);
+        response = await fetch(url, {
+          ...serverOrigin || cached?.etag ? { headers } : {},
+          ...options?.force ? { cache: "no-cache" } : {}
+        });
+      } catch (error) {
+        throw new WebsiteError(
+          `Could not load the website form: ${error instanceof Error ? error.message : String(error)}`,
+          "NETWORK_ERROR"
+        );
+      }
+      if (response.status === 304 && cached) {
+        cache.set(normalizedKey, {
+          ...cached,
+          expiresAt: Date.now() + 3e4
+        });
+        return cached.value;
+      }
+      if (response.status === 404) {
+        cache.set(normalizedKey, {
+          etag: null,
+          expiresAt: Date.now() + 15e3,
+          value: null
+        });
+        return null;
+      }
+      if (response.status === 429) {
+        throw new RateLimitError(
+          "Rate limit exceeded. Please try again later.",
+          retryAfterSeconds(response)
+        );
+      }
+      if (!response.ok) {
+        throw new WebsiteError(
+          `Could not load the website form (status ${response.status})`,
+          response.status === 403 ? "ORIGIN_NOT_ALLOWED" : "FORM_DEFINITION_ERROR",
+          { status: response.status }
+        );
+      }
+      const value = await response.json();
+      if (value.schemaVersion !== 1 || value.key !== normalizedKey || !Array.isArray(value.definition?.fields) || !Array.isArray(value.definition?.sections) || !Array.isArray(value.definition?.steps)) {
+        throw new WebsiteError(
+          "Website form returned an invalid definition",
+          "INVALID_FORM_DEFINITION"
+        );
+      }
+      cache.set(normalizedKey, {
+        etag: response.headers.get("ETag"),
+        expiresAt: Date.now() + 3e4,
+        value
+      });
+      return value;
+    },
+    async submitResponse(input) {
+      const normalizedKey = input.formKey.trim();
+      if (!isFormKey(normalizedKey)) {
+        throw new WebsiteError(
+          "formKey has an invalid format",
+          "INVALID_FORM_KEY"
+        );
+      }
+      const context = getContext();
+      const attribution = getWebsiteMarketingAttribution(context.websiteId);
+      const pageUrl = typeof window !== "undefined" ? window.location.href : void 0;
+      const referrerUrl = typeof document !== "undefined" && document.referrer ? document.referrer : void 0;
+      let response;
+      try {
+        response = await fetch(
+          `${apiUrl.replace(/\/+$/, "")}/api/v1/website/forms/responses`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              websiteSlug,
+              formKey: normalizedKey,
+              formVersion: input.formVersion,
+              definitionHash: input.definitionHash,
+              idempotencyKey: input.idempotencyKey,
+              source: input.source ?? "WEBSITE",
+              values: input.values,
+              pageUrl,
+              referrerUrl,
+              attribution: attribution ? serializeWebsiteMarketingAttribution(attribution) : null,
+              honeypot: input.honeypot ?? ""
+            })
+          }
+        );
+      } catch (error) {
+        throw new WebsiteError(
+          `Could not submit the website form: ${error instanceof Error ? error.message : String(error)}`,
+          "NETWORK_ERROR"
+        );
+      }
+      if (response.status === 429) {
+        throw new RateLimitError(
+          "Rate limit exceeded. Please try again later.",
+          retryAfterSeconds(response)
+        );
+      }
+      const result = await response.json().catch(() => null);
+      if (!response.ok) {
+        throw new WebsiteError(
+          result?.message ?? `Could not submit the website form (status ${response.status})`,
+          result?.code ?? (response.status === 403 ? "ORIGIN_NOT_ALLOWED" : "FORM_RESPONSE_ERROR"),
+          { status: response.status }
+        );
+      }
+      if (typeof result?.accepted !== "boolean" || typeof result.message !== "string") {
+        throw new WebsiteError(
+          "Website form returned an invalid response",
+          "INVALID_RESPONSE"
+        );
+      }
+      return {
+        accepted: result.accepted,
+        responseId: typeof result.responseId === "string" ? result.responseId : null,
+        message: result.message
+      };
+    }
+  };
+}
+
 // libs/sdk/src/modules/marketing.ts
 function readRetryAfter(response) {
   const value = Number(response.headers.get("Retry-After") ?? "1");
@@ -6971,6 +7136,7 @@ function createBacanoClient(config) {
     config.websiteSlug,
     getContext
   );
+  const formsModule = createFormsModule(apiUrl, config.websiteSlug, getContext);
   return {
     async init() {
       if (context) return;
@@ -7023,6 +7189,10 @@ function createBacanoClient(config) {
       getByTag: contentModule.getByTag.bind(contentModule),
       getForProduct: contentModule.getForProduct.bind(contentModule)
     },
+    forms: {
+      getDefinition: formsModule.getDefinition.bind(formsModule),
+      submitResponse: formsModule.submitResponse.bind(formsModule)
+    },
     cart: {
       getOrCreate: cartModule.getOrCreate.bind(cartModule),
       startCheckout: cartModule.startCheckout.bind(cartModule),

package/skills/bacano-figma-web/SKILL.md

@@ -91,6 +91,11 @@ Figma, desde Bacano Content o desde ambas fuentes.
   los contratos específicos del SDK.
 - No usar GraphQL directo, endpoints internos ni lógica comercial duplicada.
 - No codificar textos editables si pertenecen a Bacano Content.
+- Marcar obligatoriamente cada región visual proveniente de un `ContentEntry`
+  con `getContentEntryLocatorAttributes(entry)`. El marcador identifica la
+  entrada completa, nunca campos individuales. Conservar esta identidad al
+  transformar Content en view models y seguir
+  `STOREFRONT_CONTENT_LOCATOR.md`.
 - No alterar Baby Rex u otra referencia salvo que ese sea el proyecto indicado.
 
 Si Content todavía no existe, generar un blueprint de entrega y fixtures
@@ -147,6 +152,9 @@ proyecto.
 Antes de aprobar producción, comprobar que la fuente editorial efectiva sea
 Bacano Content. Un fixture, placeholder o fallback temporal accesible en el
 build de producción es un bloqueo, aunque visualmente coincida con Figma.
+Inspeccionar además el HTML final: toda región alimentada por una entrada debe
+conservar su marcador V1 con la key, nombre y locale correctos. Una región
+editorial sin marcador bloquea la aprobación.
 
 Al finalizar, invocar `$bacano-web` si está disponible para la auditoría de
 producción completa. Esta skill valida fidelidad y correcta integración desde

package/skills/bacano-figma-web/references/bacano-mapping.md

@@ -7,9 +7,9 @@ negocio.
 
 Antes de programar, registrar por ruta:
 
-| Ruta | Frame | Componente | Fuente | Content | Responsive | Preview | Estado |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `/` | Home desktop/mobile | `Hero` | Content | `hero_inicio` | 2 frames | activa | pendiente |
+| Ruta | Frame | Componente | Fuente | Content | Localizador | Responsive | Preview | Estado |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `/` | Home desktop/mobile | `Hero` | Content | `hero_inicio` | entrada V1 | 2 frames | activa | pendiente |
 
 Fuentes posibles: Content, catálogo estático, live state, public config,
 checkout, auth u otra operación documentada del SDK.
@@ -18,6 +18,8 @@ checkout, auth u otra operación documentada del SDK.
 
 - Usar componentes y tokens existentes antes de crear otros.
 - Mapear textos/imágenes editoriales a Content cuando deban ser administrables.
+- Para cada fuente `ContentEntry`, conservar y renderizar el marcador de entrada
+  definido en `STOREFRONT_CONTENT_LOCATOR.md`; no bajar a nivel de campo.
 - Si el equipo de Content y desarrollo trabajan en tiempos distintos, seguir
   [content-workflow.md](content-workflow.md) y mantener un único contrato de
   datos entre fixtures temporales y Bacano real.

package/skills/bacano-figma-web/references/content-workflow.md

@@ -35,6 +35,10 @@ reduzca duplicación real.
   consumidores.
 - No hacer depender la UI del shape crudo de Content: fixture y mapper real
   deben converger en el mismo view model.
+- Conservar en ese view model los atributos producidos por
+  `getContentEntryLocatorAttributes(entry)`. Toda región visual administrada
+  por una entrada debe exponerlos en su contenedor DOM exterior; no se marcan
+  campos individuales.
 
 ## 2. Elegir el punto de partida
 
@@ -138,6 +142,10 @@ Bacano mapper ─┘
 El cambio de fuente debe ocurrir en el loader o repositorio de contenido, nunca
 mediante condicionales repartidos por los componentes.
 
+Los fixtures pueden simular el view model, pero no deben inventar marcadores de
+entrada en producción. El marcador definitivo se deriva del `ContentEntry`
+real para que nombre, key y locale no diverjan.
+
 ## 5. Entrega al equipo de Content
 
 Entregar una tabla legible con:
@@ -167,7 +175,9 @@ Antes de retirar el fixture:
 2. Validar campos requeridos, media y contenido largo.
 3. Comparar la página con Figma usando Content real.
 4. Verificar preview si la capacidad está activa.
-5. Eliminar el fixture del camino de ejecución, no necesariamente de los tests.
+5. Inspeccionar el HTML y confirmar los marcadores definidos en
+   `STOREFRONT_CONTENT_LOCATOR.md` para cada región editorial.
+6. Eliminar el fixture del camino de ejecución, no necesariamente de los tests.
 
 En producción no se permite fallback silencioso a fixtures. Si una página
 depende de contenido temporal, reportar `❌ NO LISTO` con las rutas y secciones

package/skills/bacano-figma-web/references/implementation-quality.md

@@ -58,6 +58,18 @@ no aceptar una ruta arbitraria solo porque coincide con una cadena. Preview
 reutiliza componentes y mappers de producción, permanece fuera del sitemap y
 no habilita funciones transaccionales o marketing.
 
+## Trazabilidad editorial
+
+Al mapear un `ContentEntry`, conservar los atributos retornados por
+`getContentEntryLocatorAttributes(entry)` hasta el componente visual. Aplicar
+el spread al `section`, `article`, banner o tarjeta exterior que representa la
+entrada. No repetirlo en cada título o párrafo. Si una tarjeta proviene de otra
+entrada referenciada, esa tarjeta lleva su propio marcador anidado.
+
+La salida final debe cumplir `STOREFRONT_CONTENT_LOCATOR.md`. Verificar el HTML
+generado; encontrar la llamada al helper en TypeScript no demuestra que el
+marcador haya llegado al DOM.
+
 ## Diagnóstico antes de cambiar código
 
 Un `ORIGIN_NOT_ALLOWED` o un `403` al resolver la configuración durante el

package/skills/bacano-web/SKILL.md

@@ -47,10 +47,14 @@ Después leer solo:
 Si `@bacano/sdk` está disponible, leer sus contratos canónicos aplicables antes
 de proponer cambios. Como mínimo revisar `STOREFRONT_LEGAL.md`,
 `STOREFRONT_MARKETING.md`, `STOREFRONT_PERFORMANCE.md` y
-`STOREFRONT_PREVIEW.md`; añadir
+`STOREFRONT_PREVIEW.md`; si el sitio renderiza Bacano Content, leer también y
+aplicar obligatoriamente `STOREFRONT_CONTENT_LOCATOR.md`; añadir
 `AUTHENTICATION.md`, `STOREFRONT_LEADS.md`, `STOREFRONT_CLARITY.md` y
 otros contratos únicamente cuando esas capacidades existan. Leer
 `STOREFRONT_CONSTRUCTION.md` cuando el website permita ocultarse temporalmente.
+Si existen formularios administrados desde Bacano, leer obligatoriamente
+`STOREFRONT_FORMS.md` y
+[references/forms.md](references/forms.md) antes de auditarlos o modificarlos.
 
 ## 3. Auditar sin alterar el sistema
 
@@ -67,6 +71,8 @@ ejecutar compras/pagos sin autorización explícita.
 5. Comparar router, salida del build y sitemap; ninguna ruta pública debe
    omitirse silenciosamente.
 6. Inspeccionar HTML generado, metadata, JSON-LD, media y enlaces internos.
+   Si existe Content, comparar las entradas renderizadas con los marcadores V1
+   presentes en ese HTML; revisar únicamente el JSX no es evidencia suficiente.
 7. Si existe un dominio o una aplicación ejecutable, auditar sus rutas reales,
    la consola y un trace de red con nombres y conteos de operaciones GraphQL.
 8. Probar vistas representativas desktop y mobile.

package/skills/bacano-web/references/common.md

@@ -29,6 +29,13 @@ función apagada en un bloqueo artificial.
 - Comprobar que preview, callbacks, cuenta, checkout y respuestas de pago no se
   indexen cuando corresponda.
 - Validar estados vacío, loading, error y ausencia de Content opcional.
+- `P0`: toda región visual cuya fuente sea un `ContentEntry` expone en el HTML
+  final el marcador de `STOREFRONT_CONTENT_LOCATOR.md`, con la key, nombre y
+  locale de la entrada fuente. El control es por entrada completa, no por campo.
+- Comparar inventario de entradas y regiones. Permitir marcadores repetidos si
+  una entrada aparece en varios lugares y marcadores anidados cuando una tarjeta
+  proviene de otra entrada referenciada. No exigirlos a código/i18n, catálogo,
+  `publicConfig` ni documentos legales.
 
 ## SEO y compartición
 

package/skills/bacano-web/references/forms.md

@@ -0,0 +1,67 @@
+# Formularios públicos de Bacano
+
+Aplicar este contrato cuando el sitio muestre al menos un formulario administrado
+desde Bacano. Leer también `STOREFRONT_FORMS.md` completo desde el paquete SDK.
+
+## Implementación oficial
+
+- Clasificar formularios como `ACTIVA`, `INACTIVA` o `BLOQUEADA` en la matriz de
+  capacidades.
+- Usar `BacanoForm` desde `@bacano/sdk/react/forms` o un renderer propio basado
+  exclusivamente en `useBacanoForm()`.
+- Reutilizar el único `BacanoProvider` y cliente global del sitio. No crear otro
+  cliente, consultar GraphQL ni llamar endpoints internos.
+- No duplicar keys, validaciones, opciones o estructura en un esquema local.
+- En Static First, obtener la definición durante build/servidor y entregarla
+  como `initialForm`. La revalidación runtime no debe borrar el HTML inicial.
+- Renderizar campos directos, secciones visuales y pasos según su semántica. Una
+  sección no es un paso y no debe inventar navegación.
+- Las listas de Content llegan resueltas por Bacano; el storefront no reconstruye
+  opciones ni consulta Content por separado.
+
+## Envío y seguridad
+
+- Enviar mediante `client.forms.submitResponse()` o el envío interno de
+  `BacanoForm`.
+- `honeypot` es un campo trampa, no un nonce, timestamp, UUID ni dato del
+  visitante. `BacanoForm` lo administra. En un renderer manual, omitirlo salvo
+  que exista un input trampa realmente oculto; para una persona siempre debe
+  permanecer vacío y el autocompletado no debe llenarlo.
+- `accepted: true` con `responseId: null` es una aceptación silenciosa antispam:
+  no demuestra que la respuesta fue guardada. La verificación funcional exige
+  un UUID y la respuesta visible una sola vez en Bacano.
+- Los datos de contacto deben conservar su semántica: usar campos `email` y
+  `phone`. Un campo `text` llamado correo o teléfono se guarda como texto libre
+  y no alimenta los datos de contacto normalizados para CRM o automatizaciones.
+- Conservar una `idempotencyKey` durante reintentos del mismo intento lógico.
+- Enviar la versión y `definitionHash` exactos de la definición renderizada.
+- Respetar estados `ACTIVE` y `PAUSED`; no renderizar borradores o archivados.
+- No escribir respuestas o PII en consola, analítica, URLs o logs del storefront.
+- En `CAPTURE_LEAD`, Bacano conserva primero la respuesta y resuelve la identidad
+  internamente. No afirmar al visitante que se creó un lead o que ya era cliente:
+  la respuesta pública es genérica y no expone ese resultado.
+- No afirmar que se envió un correo, se entregó un cupón o se abrió una solicitud
+  si esa acción aún no está implementada y verificada en Bacano.
+- Una brecha del SDK se reporta; nunca se resuelve con GraphQL directo ni una API
+  paralela del storefront.
+
+## Verificaciones obligatorias
+
+- Formulario activo: estructura, labels, required, ayudas, opciones y envío.
+- Formulario pausado e inexistente: mensaje seguro y ningún envío.
+- Versión desactualizada: refresh oficial y conservación controlada de datos.
+- Doble clic y reintento: una sola respuesta por intento idempotente.
+- Error de red: estado recuperable sin promesa falsa de recepción.
+- Persistencia: la respuesta aparece una sola vez en Bacano con versión, origen y
+  snapshot correctos.
+- Autocompletado: completar datos con el navegador o un gestor de contraseñas no
+  llena el honeypot ni produce `responseId: null`.
+- Semántica: correo y teléfono usan `email` y `phone`; no se infieren por label o
+  key.
+- Accesibilidad: label asociado, foco, teclado, mensajes de error y progreso de
+  pasos comprensibles.
+- Static First: el HTML exportado conserva el formulario cuando corresponde.
+
+Reportar evidencia con la key pública, ruta, archivo del renderer, requests
+observados y prueba de persistencia. Nunca incluir valores personales reales en
+el informe.

package/skills/bacano-web/references/informational.md

@@ -12,6 +12,9 @@ Aplicar además de los controles comunes.
 
 ## Formularios y contacto
 
+- Los formularios administrados desde Bacano cumplen
+  [forms.md](forms.md), usan el renderer o hook oficial y conservan su definición
+  estática cuando corresponde.
 - Distinguir formularios informativos/PQRS de capturas comerciales.
 - Newsletter, cupón o interés comercial usan
   `client.marketing.captureLead()` y el texto vigente de autorización.

package/types.d.ts

@@ -149,6 +149,93 @@ export interface WebsiteCampaignCaptureResult {
     accepted: boolean;
     message: string;
 }
+export type WebsiteFormAction = "STORE_RESPONSE" | "CAPTURE_LEAD";
+export type WebsiteFormStatus = "ACTIVE" | "PAUSED";
+export type WebsiteFormFieldType = "text" | "textarea" | "email" | "phone" | "number" | "date" | "select" | "radio" | "multi_select" | "checkbox";
+export interface WebsiteFormOption {
+    value: string;
+    label: string;
+}
+export type WebsiteFormOptionSource = {
+    kind: "INLINE";
+    options: WebsiteFormOption[];
+} | {
+    kind: "CONTENT_LIST";
+    listKey: string;
+};
+export interface WebsiteFormField {
+    key: string;
+    label: string;
+    type: WebsiteFormFieldType;
+    required: boolean;
+    placeholder?: string | null;
+    helpText?: string | null;
+    optionSource?: WebsiteFormOptionSource | null;
+    /** Resolved public options. Content List internals never need rebuilding by a storefront. */
+    options?: WebsiteFormOption[];
+    validation: {
+        min?: number | null;
+        max?: number | null;
+        minLength?: number | null;
+        maxLength?: number | null;
+    };
+}
+export interface WebsiteFormSection {
+    key: string;
+    title: string;
+    description?: string | null;
+    fields: WebsiteFormField[];
+}
+export interface WebsiteFormStep {
+    key: string;
+    title: string;
+    description?: string | null;
+    fields: WebsiteFormField[];
+    sections: WebsiteFormSection[];
+}
+export interface WebsiteFormDefinition {
+    schemaVersion: 1;
+    submitLabel: string;
+    successMessage: string;
+    unavailableMessage: string;
+    fields: WebsiteFormField[];
+    sections: WebsiteFormSection[];
+    steps: WebsiteFormStep[];
+}
+export interface WebsitePublishedForm {
+    schemaVersion: 1;
+    id: string;
+    key: string;
+    name: string;
+    description: string;
+    action: WebsiteFormAction;
+    status: WebsiteFormStatus;
+    version: number;
+    publishedAt: string;
+    definitionHash: string;
+    definition: WebsiteFormDefinition;
+}
+export type WebsiteFormResponseSource = "WEBSITE" | "QR";
+export type WebsiteFormResponseValue = string | string[] | boolean;
+export interface WebsiteFormResponseInput {
+    formKey: string;
+    formVersion: number;
+    definitionHash: string;
+    idempotencyKey: string;
+    values: Record<string, WebsiteFormResponseValue>;
+    source?: WebsiteFormResponseSource;
+    /**
+     * Bot-trap field, not a token or nonce. Omit it unless a real hidden trap is
+     * rendered; legitimate visitors must always submit an empty value.
+     */
+    honeypot?: string;
+}
+export interface WebsiteFormResponseResult {
+    accepted: boolean;
+    /** A null value is not proof of persistence (for example, an anti-bot response). */
+    responseId: string | null;
+    message: string;
+}
 export type ResolvedWebsitePublicConfig = WebsitePublicConfig & {
     branding: WebsiteBrandingPublicConfig;
     legal: WebsiteLegalPublicConfig;