@bacano/sdk 1.1.15 → 1.1.18

package/README.md

@@ -112,6 +112,20 @@ Commercial forms and newsletter subscriptions must follow
 Bacano owns consent evidence, identity resolution, attribution and idempotent
 lead capture through the SDK.
 
+Website forms defined and published from Bacano use the additive contract in
+[`STOREFRONT_FORMS.md`](./STOREFRONT_FORMS.md). Storefronts can mount the
+official `BacanoForm` renderer or consume the same typed definition through
+`useBacanoForm()` without GraphQL, HTML stored in the database or a rebuild
+after each publication.
+
+Every visible region sourced from a Bacano `ContentEntry` must expose the
+entry-level marker defined in
+[`STOREFRONT_CONTENT_LOCATOR.md`](./STOREFRONT_CONTENT_LOCATOR.md). Use
+`getContentEntryLocatorAttributes(entry)` on the outer section or card so an
+authorized internal browser tool can show the entry name and open its Bacano
+editor. This contract identifies entries only; it does not expose field-level
+editing or grant backoffice access.
+
 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

package/STOREFRONT_CONTENT_LOCATOR.md

@@ -0,0 +1,111 @@
+# Localizador de entradas de Content
+
+Este documento define el contrato público V1 que permite reconocer desde el
+navegador qué entrada de Bacano Content produce una región visible de una web.
+El objetivo es únicamente **identificar la entrada y abrir su editor**. No es
+edición inline y no identifica campos individuales.
+
+## Contrato obligatorio
+
+Toda región visual cuyo contenido editorial provenga de un `ContentEntry` debe
+marcar su elemento DOM exterior significativo con:
+
+```html
+<section
+  data-bacano-content-entry="v1"
+  data-bacano-entry-key="seccion-de-servicios"
+  data-bacano-entry-name="Sección de servicios"
+  data-bacano-entry-locale="es-CO"
+>
+  <!-- contenido visible -->
+</section>
+```
+
+Usar el helper oficial evita diferencias en nombres, versión y normalización:
+
+```tsx
+import {
+  getContentEntryLocatorAttributes,
+  type ContentEntry,
+} from "@bacano/sdk";
+
+function ServicesSection({ entry }: { entry: ContentEntry }) {
+  return (
+    <section {...getContentEntryLocatorAttributes(entry)}>
+      {/* La sección puede consumir un view model derivado de entry. */}
+    </section>
+  );
+}
+```
+
+El helper falla si la entrada no tiene una `key` estable o un `locale`. Una
+región que no puede abrir una entrada inequívoca no debe aparentar que sí puede.
+
+## Granularidad
+
+- Marcar una vez el bloque visual administrable: `section`, `article`, banner,
+  tarjeta o contenedor equivalente.
+- No marcar títulos, párrafos, botones ni campos individuales dentro del mismo
+  bloque.
+- Si una tarjeta visible usa otra entrada referenciada, la tarjeta recibe su
+  propio marcador anidado. El espacio restante conserva el marcador de la
+  entrada contenedora.
+- Si una entrada produce varias regiones independientes, cada región puede
+  repetir el mismo marcador.
+- No marcar texto perteneciente al código/i18n, productos del catálogo,
+  configuración pública ni documentos legales como si fueran Content.
+
+Los mappers pueden transformar `contentJson`, pero deben conservar el origen
+editorial necesario para llamar el helper. Por ejemplo:
+
+```ts
+const section = {
+  locator: getContentEntryLocatorAttributes(entry),
+  title: readTitle(entry.contentJson),
+};
+```
+
+```tsx
+<section {...section.locator}>{section.title}</section>
+```
+
+## Responsabilidades del consumidor
+
+Una extensión o herramienta de inspección:
+
+1. busca `[data-bacano-content-entry="v1"]`;
+2. muestra `data-bacano-entry-name` al usuario;
+3. usa `data-bacano-entry-key` y `data-bacano-entry-locale` para construir la
+   navegación hacia el backoffice;
+4. deja autenticación, empresa y permisos bajo control de Bacano.
+
+El SDK no publica una URL de administración ni abre ventanas. Ese destino
+pertenece a la herramienta interna y puede cambiar entre ambientes.
+
+## Seguridad y salida estática
+
+Los cuatro atributos contienen exclusivamente identidad editorial ya pública:
+versión, key, nombre y locale de una entrada publicada. Nunca incluir tokens,
+URLs administrativas firmadas, secretos, IDs de usuarios ni datos privados.
+
+Los marcadores no conceden permisos. El backoffice debe autenticar y autorizar
+cualquier lectura o modificación. En exports estáticos los atributos quedan
+materializados junto con el contenido publicado y se actualizan en el siguiente
+build.
+
+## Verificación
+
+Antes de publicar una web que usa Bacano Content:
+
+- inventariar las entradas que producen regiones visibles;
+- inspeccionar el HTML final, no solo JSX o componentes;
+- comprobar que cada región tiene exactamente la key, nombre y locale de su
+  entrada fuente;
+- probar marcadores anidados cuando una entrada contenedora renderiza entradas
+  referenciadas;
+- comprobar que activar una herramienta de localización no altera navegación,
+  layout ni accesibilidad cuando vuelve a desactivarse.
+
+Una región editorial sin marcador o con una key distinta de su fuente es un
+fallo de integración, porque impide localizar de manera confiable el contenido
+que la web declara administrable.

package/STOREFRONT_FORMS.md

@@ -0,0 +1,211 @@
+# Formularios de websites
+
+Los formularios públicos de Bacano son definiciones tipadas y versionadas. El
+storefront decide dónde se muestran y cómo lucen; Bacano controla su estructura,
+estado y validaciones. La definición nunca contiene HTML ni JavaScript arbitrario.
+
+## Renderer oficial para React
+
+Monta un único `BacanoProvider` global y usa la key pública configurada en el ERP:
+
+```tsx
+import { BacanoForm } from "@bacano/sdk/react/forms";
+
+export function ContactForm() {
+  return (
+    <BacanoForm
+      formKey="contacto"
+      classNames={{ root: "contact-form", field: "contact-field" }}
+    />
+  );
+}
+```
+
+`BacanoForm` soporta campos directos, secciones visuales y pasos reales,
+validación nativa, opciones manuales, Listas de Content y el envío oficial de
+respuestas. Si se
+omite `onSubmit`, utiliza el mismo `BacanoClient` global, genera una clave
+idempotente estable y llama `client.forms.submitResponse(...)`. Un formulario
+pausado muestra su mensaje de indisponibilidad y deja de operar sin reconstruir
+el storefront.
+
+## Estructura del formulario
+
+La definición tiene tres niveles explícitos:
+
+- `fields`: campos directos de un formulario continuo.
+- `sections`: agrupaciones visuales opcionales dentro del formulario continuo.
+- `steps`: etapas reales de un formulario multipaso. Cada paso puede contener
+  campos directos y secciones.
+
+Un formulario continuo puede tener campos, secciones o ambos. Cuando existen
+pasos, `fields` y `sections` de la raíz deben estar vacíos: todo el contenido
+pertenece a un paso. Las secciones no crean navegación ni cambian el envío; los
+pasos sí muestran avance y controles para continuar o regresar. Un formulario
+también puede existir sin secciones ni pasos, usando únicamente campos directos.
+
+`onSubmit` permanece disponible para experiencias personalizadas. No debe
+usarse para llamar GraphQL, endpoints internos ni crear una persistencia
+paralela.
+
+## Renderer personalizado
+
+```tsx
+import { useBacanoState } from "@bacano/sdk/react";
+import { useBacanoForm } from "@bacano/sdk/react/forms";
+
+export function BrandedContactForm() {
+  const { client } = useBacanoState();
+  const { form, loading, error, refresh } = useBacanoForm("contacto");
+
+  if (loading || !client) return null;
+  if (error || !form) return <p>Formulario no disponible.</p>;
+  if (form.status === "PAUSED") {
+    return <p>{form.definition.unavailableMessage}</p>;
+  }
+
+  const submit = async (values: Record<string, string | string[] | boolean>) =>
+    client.forms.submitResponse({
+      formKey: form.key,
+      formVersion: form.version,
+      definitionHash: form.definitionHash,
+      idempotencyKey: crypto.randomUUID(),
+      values,
+    });
+
+  return <CustomRenderer definition={form.definition} onSubmit={submit} />;
+}
+```
+
+El renderer personalizado puede cambiar componentes y estilos, pero debe usar
+los campos, keys, opciones y validaciones entregados por el SDK. No debe crear
+un segundo cliente, resolver el website nuevamente ni usar GraphQL directo.
+
+## Honeypot y confirmación de persistencia
+
+`honeypot` es un campo trampa contra bots, no un token de seguridad. No es una
+marca de tiempo, un UUID, un número aleatorio ni un identificador del visitante.
+Un usuario real debe enviarlo siempre vacío.
+
+- `BacanoForm` administra el honeypot internamente. El storefront no debe crear
+  otro ni asignarle un valor.
+- Un renderer personalizado debe omitir `honeypot` en
+  `client.forms.submitResponse(...)` salvo que implemente deliberadamente un
+  input trampa oculto. El SDK lo enviará como cadena vacía por defecto.
+- Si se implementa el input trampa, debe quedar fuera del flujo visual y del
+  teclado, con autocompletado desactivado. Nunca debe reutilizar un campo real ni
+  recibir sugerencias del navegador o de un gestor de contraseñas.
+- Bacano responde de manera deliberadamente genérica ante un honeypot lleno:
+  `accepted: true` y `responseId: null`. La respuesta no se persiste y el bot no
+  descubre que fue detectado.
+- Para una prueba funcional o aprobación de producción, el envío debe devolver
+  `accepted: true` y un UUID en `responseId`, y debe aparecer una sola vez en
+  Respuestas dentro de Bacano.
+
+No uses `responseId: null` para mostrar información distinta al visitante. Es
+una señal técnica para pruebas y observabilidad segura, no un mensaje que deba
+revelar la protección antispam.
+
+## Tipos semánticos de contacto
+
+La etiqueta y la key no sustituyen el tipo del campo. Si un dato representa un
+correo o un teléfono, el formulario debe definirlo como `email` o `phone`:
+
+- Bacano valida el formato según el tipo declarado.
+- Las respuestas conservan todos los valores, pero solo los campos `email` y
+  `phone` alimentan los datos de contacto normalizados de la respuesta.
+- Un campo `text` llamado `correo`, `email`, `telefono` o similar continúa
+  siendo texto libre. No debe dependerse de su nombre para CRM, leads o futuras
+  automatizaciones.
+
+Antes de publicar, revisa que los campos destinados a identificar o contactar a
+la persona tengan el tipo correcto. Cambiar únicamente su etiqueta no corrige el
+contrato de datos.
+
+## Next.js y Static First
+
+Obtén la definición durante el build o desde un Server Component usando el
+mismo cliente configurado para el website. Después entrégala al renderer como
+`initialForm`:
+
+```tsx
+const initialForm = await bacano.forms.getDefinition("contacto");
+
+return (
+  <BacanoForm
+    formKey="contacto"
+    initialForm={initialForm}
+  />
+);
+```
+
+Así, el HTML inicial contiene el formulario aunque JavaScript todavía no haya
+hidratado. El provider global reutiliza esa definición y la revalida en runtime
+para reflejar una publicación o pausa sin rebuild. No ocultes el formulario
+estático detrás de un `loadingFallback` global ni crees otro `BacanoClient` para
+consultarlo.
+
+## Contrato operativo
+
+- `DRAFT`: no es público.
+- `ACTIVE`: entrega la última versión publicada.
+- `PAUSED`: conserva definición y mensaje, pero no acepta nuevos envíos.
+- `ARCHIVED`: deja de ser público y conserva auditoría.
+- Publicar crea una versión inmutable; editar modifica únicamente el borrador.
+- Los cambios publicados se revalidan en runtime y no requieren rebuild.
+- La revalidación usa caché corta y ETag; una falla temporal no elimina una
+  definición válida que ya fue generada estáticamente.
+- Una Lista de Content se resuelve en Bacano. El storefront recibe opciones
+  públicas listas para renderizar.
+- Cada envío incluye la versión y huella exactas de la definición publicada.
+  Una página desactualizada recibe `FORM_VERSION_MISMATCH` y debe refrescar.
+- `idempotencyKey` identifica un intento lógico. Repetir la misma clave y el
+  mismo contenido devuelve la respuesta existente; reutilizarla con otro
+  contenido se rechaza.
+- Bacano deriva empresa y website desde `websiteSlug`; el storefront no envía
+  identificadores internos ni controla el tenant.
+- La API vuelve a validar tipos, requeridos, rangos y opciones de listas. La
+  validación del navegador mejora la experiencia, pero no es autoritativa.
+- URL, referidor y atribución se sanean. Las respuestas y datos personales no
+  se escriben en logs.
+- `pageUrl`, `referrerUrl` y la URL de atribución aceptan únicamente HTTP o
+  HTTPS. No envíes protocolos locales, ejecutables o de datos.
+- Los teléfonos admiten un `+` inicial y separadores habituales; Bacano los
+  normaliza antes de resolver identidad y rechaza letras o signos mal ubicados.
+- Los números usan notación decimal o científica explícita. Valores ambiguos
+  como `0x10` o `3 unidades` se rechazan aunque JavaScript pudiera convertirlos.
+- Un checkbox opcional omitido se conserva como `null`; uno requerido debe
+  enviarse expresamente como `true`.
+- Una falla de correo, CRM o automatización no revierte la respuesta.
+- `STORE_RESPONSE` conserva la respuesta sin crear un lead.
+- `CAPTURE_LEAD` conserva primero la respuesta y después resuelve internamente
+  la identidad canónica. Reutiliza un lead o cliente existente, crea un lead
+  cuando corresponde y manda a revisión las coincidencias contradictorias de
+  correo y teléfono sin fusionarlas automáticamente.
+- El resultado público continúa siendo deliberadamente genérico. El storefront
+  no recibe ni debe inferir si Bacano creó un lead, encontró un cliente o marcó
+  una identidad para revisión.
+
+## Checklist mínimo del storefront
+
+- Usar un solo `BacanoProvider` y el cliente global ya inicializado.
+- Renderizar con `BacanoForm` o con `useBacanoForm`; nunca copiar la definición
+  a un esquema local ni consultar GraphQL directamente.
+- Pueden coexistir varios `BacanoForm` en una página. El renderer oficial aísla
+  los identificadores de sus controles; no construyas IDs globales solo con la
+  key del campo.
+- Entregar `initialForm` cuando la página se genera de forma estática.
+- Respetar `ACTIVE`, `PAUSED`, versión y `definitionHash` sin inferir estados.
+- Mantener una `idempotencyKey` estable durante los reintentos del mismo envío.
+- Probar formulario activo, pausado, inexistente, versión desactualizada,
+  reintento idempotente y error de red.
+- Confirmar en Bacano que una respuesta real quedó persistida antes de aprobar
+  el flujo; no basta con mostrar el mensaje de éxito del navegador.
+- Probar autocompletado del navegador y gestores de contraseñas: ningún campo
+  real puede llenar el honeypot. Un envío real debe devolver un UUID como
+  `responseId`; `null` no demuestra persistencia.
+- Verificar que correos y teléfonos utilicen los tipos `email` y `phone`, no
+  campos de texto con una etiqueta parecida.
+- No prometer correo, cupón, solicitud ni automatización mientras la capacidad
+  no esté implementada y activa en Bacano. Aunque `CAPTURE_LEAD` esté activo,
+  el mensaje público no debe afirmar qué identidad interna se creó o reutilizó.

package/client.d.ts

@@ -1,4 +1,4 @@
-import type { BacanoClientConfig, BacanoClientContext, Brand, Cart, CartItem, CatalogAttributeList, CatalogCategoryList, CatalogPageResult, CheckoutResult, CheckoutSubmission, ContentEntry, CustomerAddress, CustomerProfile, CustomerProfileUpdate, GetAttributeListOptions, GetCatalogPageOptions, GetCategoryListOptions, GetContentOptions, GetOrdersOptions, GetProductFiltersOptions, GetProductRecommendationsOptions, GetProductSeoEntriesOptions, GetProductsOptions, GetSearchSuggestionsOptions, GetStaticCatalogBootstrapOptions, GetStaticCatalogSnapshotOptions, Order, Product, ProductAvailability, ProductCategory, ProductContentBlock, ProductFilters, ProductRecommendationsResult, ProductSeoEntriesResult, ProductVariantLiveState, PublicOrder, PublicOrderLookupInput, SearchSuggestion, StartGuestCheckoutInput, StaticCatalogBootstrap, StaticCatalogSnapshot, WaitForPublicOrderPaymentInput, WebsiteCampaignCaptureInput, WebsiteCampaignCaptureResult, WebsiteCheckoutAddress, WebsiteCheckoutItem, WebsiteCouponActionResult, WebsiteDeliveryOption, WebsiteFreeShippingProgress, WebsiteFulfillmentFamily, WebsiteGuestContact, WebsiteLocationOptions, WebsitePaymentMethod, WebsitePaymentOption, WebsitePaymentSessionResult, WebsiteShippingPolicy, WebsiteShippingQuote } from "./types";
+import type { BacanoClientConfig, BacanoClientContext, Brand, Cart, CartItem, CatalogAttributeList, CatalogCategoryList, CatalogPageResult, CheckoutResult, CheckoutSubmission, ContentEntry, CustomerAddress, CustomerProfile, CustomerProfileUpdate, GetAttributeListOptions, GetCatalogPageOptions, GetCategoryListOptions, GetContentOptions, GetOrdersOptions, GetProductFiltersOptions, GetProductRecommendationsOptions, GetProductSeoEntriesOptions, GetProductsOptions, GetSearchSuggestionsOptions, GetStaticCatalogBootstrapOptions, GetStaticCatalogSnapshotOptions, Order, Product, ProductAvailability, ProductCategory, ProductContentBlock, ProductFilters, ProductRecommendationsResult, ProductSeoEntriesResult, ProductVariantLiveState, PublicOrder, PublicOrderLookupInput, SearchSuggestion, StartGuestCheckoutInput, StaticCatalogBootstrap, StaticCatalogSnapshot, WaitForPublicOrderPaymentInput, WebsiteCampaignCaptureInput, WebsiteCampaignCaptureResult, WebsiteCheckoutAddress, WebsiteCheckoutItem, WebsiteCouponActionResult, WebsiteDeliveryOption, WebsiteFormResponseInput, WebsiteFormResponseResult, WebsiteFreeShippingProgress, WebsiteFulfillmentFamily, WebsiteGuestContact, WebsiteLocationOptions, WebsitePaymentMethod, WebsitePaymentOption, WebsitePaymentSessionResult, WebsitePublishedForm, WebsiteShippingPolicy, WebsiteShippingQuote } from "./types";
 export interface BacanoClient {
     /** Initialize the client and resolve its website context. */
     init(): Promise<void>;
@@ -34,6 +34,13 @@ export interface BacanoClient {
         getByTag(tag: string, opts?: GetContentOptions): Promise<ContentEntry[]>;
         getForProduct(productId: string, opts?: GetContentOptions): Promise<ProductContentBlock[]>;
     };
+    forms: {
+        /** Returns the current published definition or null when it is unavailable. */
+        getDefinition(formKey: string, options?: {
+            force?: boolean;
+        }): Promise<WebsitePublishedForm | null>;
+        submitResponse(input: WebsiteFormResponseInput): Promise<WebsiteFormResponseResult>;
+    };
     cart: {
         getOrCreate(contact?: WebsiteGuestContact, fulfillmentFamily?: WebsiteFulfillmentFamily): Promise<Cart>;
         startCheckout(input: StartGuestCheckoutInput): Promise<Cart>;

package/content-entry-locator.d.ts

@@ -0,0 +1,16 @@
+import type { ContentEntry } from "./types";
+export declare const CONTENT_ENTRY_LOCATOR_VERSION: "v1";
+export declare const CONTENT_ENTRY_LOCATOR_SELECTOR: "[data-bacano-content-entry=\"v1\"]";
+export type ContentEntryLocatorSource = Pick<ContentEntry, "key" | "locale" | "name">;
+export interface ContentEntryLocatorAttributes {
+    "data-bacano-content-entry": typeof CONTENT_ENTRY_LOCATOR_VERSION;
+    "data-bacano-entry-key": string;
+    "data-bacano-entry-locale": string;
+    "data-bacano-entry-name": string;
+}
+/**
+ * Adds the public, non-authoritative marker consumed by Bacano's content
+ * locator. Spread the result only on the outermost meaningful DOM element
+ * whose visible editorial content is owned by the entry.
+ */
+export declare function getContentEntryLocatorAttributes(entry: ContentEntryLocatorSource): ContentEntryLocatorAttributes;

package/index.cjs

@@ -21,6 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AuthError: () => AuthError,
+  CONTENT_ENTRY_LOCATOR_SELECTOR: () => CONTENT_ENTRY_LOCATOR_SELECTOR,
+  CONTENT_ENTRY_LOCATOR_VERSION: () => CONTENT_ENTRY_LOCATOR_VERSION,
   CheckoutError: () => CheckoutError,
   GraphQLRequestError: () => GraphQLRequestError,
   MARKETING_SCHEMA_VERSION: () => MARKETING_SCHEMA_VERSION,
@@ -38,6 +40,7 @@ __export(index_exports, {
   createWebsiteMarketingRuntime: () => createWebsiteMarketingRuntime,
   formatMediaSrcSet: () => formatMediaSrcSet,
   getAllowedMarketingParameters: () => getAllowedMarketingParameters,
+  getContentEntryLocatorAttributes: () => getContentEntryLocatorAttributes,
   getPrimaryProductImage: () => getPrimaryProductImage,
   getProductDetailVariants: () => getProductDetailVariants,
   getProductImages: () => getProductImages,
@@ -66,10 +69,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";
   }
@@ -6115,6 +6118,171 @@ function createWebsiteMarketingRuntime(options) {
   };
 }
 
+// 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");
@@ -6641,6 +6809,7 @@ function createBacanoClient(config) {
     config.websiteSlug,
     getContext
   );
+  const formsModule = createFormsModule(apiUrl, config.websiteSlug, getContext);
   return {
     async init() {
       if (context) return;
@@ -6693,6 +6862,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),
@@ -6734,3 +6907,23 @@ function createBacanoClient(config) {
     }
   };
 }
+
+// libs/sdk/src/content-entry-locator.ts
+var CONTENT_ENTRY_LOCATOR_VERSION = "v1";
+var CONTENT_ENTRY_LOCATOR_SELECTOR = `[data-bacano-content-entry="${CONTENT_ENTRY_LOCATOR_VERSION}"]`;
+function getContentEntryLocatorAttributes(entry) {
+  const key = entry.key?.trim();
+  if (!key) {
+    throw new Error("A Bacano Content locator requires a stable entry key.");
+  }
+  const locale = entry.locale.trim();
+  if (!locale) {
+    throw new Error("A Bacano Content locator requires an entry locale.");
+  }
+  return {
+    "data-bacano-content-entry": CONTENT_ENTRY_LOCATOR_VERSION,
+    "data-bacano-entry-key": key,
+    "data-bacano-entry-locale": locale,
+    "data-bacano-entry-name": entry.name.trim() || key
+  };
+}

package/index.d.ts

@@ -1,5 +1,7 @@
 export type { BacanoClient } from "./client";
 export { createBacanoClient } from "./client";
+export type { ContentEntryLocatorAttributes, ContentEntryLocatorSource, } from "./content-entry-locator";
+export { CONTENT_ENTRY_LOCATOR_SELECTOR, CONTENT_ENTRY_LOCATOR_VERSION, getContentEntryLocatorAttributes, } from "./content-entry-locator";
 export { AuthError, CheckoutError, GraphQLRequestError, NotInitializedError, RateLimitError, WebsiteError, } from "./errors";
 export type { WebsiteAdvertisingConsent, WebsiteMarketingAttribution, WebsiteMarketingBrowserEvent, WebsiteMarketingBrowserEventName, WebsiteMarketingContactPlacement, WebsiteMarketingDiagnostic, WebsiteMarketingItem, WebsiteMarketingRuntime, WebsiteMarketingRuntimeOptions, WebsiteMarketingScriptLoadStrategy, WebsiteMarketingTouchpoint, } from "./marketing";
 export { captureWebsiteMarketingAttribution, createWebsiteMarketingRuntime, getAllowedMarketingParameters, getWebsiteMarketingAttribution, MARKETING_SCHEMA_VERSION, sanitizeMarketingUrl, WEBSITE_MARKETING_CONTACT_PLACEMENTS, } from "./marketing";
@@ -7,4 +9,4 @@ export type { MediaResponsiveSource, MediaResponsiveSourceOptions, MediaTransfor
 export { buildStorageContentMediaUrls, buildStorageFileUrl, buildStorageMediaUrls, buildStorageResponsiveSources, buildStorageTransformedFileUrl, formatMediaSrcSet, } from "./media";
 export { getWebsiteContextFromPublicConfig, getWebsitePublicConfig, } from "./modules/auth";
 export { getPrimaryProductImage, getProductDetailVariants, getProductImages, getProductMediaByKind, getProductMediaKind, getProductVideos, resolveProductPricing, } from "./modules/catalog";
-export type { AccessTokenProvider, AttributeFilter, BacanoClientConfig, BacanoClientContext, Brand, Cart, CartItem, CatalogAttributeList, CatalogAttributeListFilters, CatalogAttributeListItem, CatalogAttributeListValue, CatalogCategoryList, CatalogCategoryListItem, CatalogCategoryListItemSourceType, CheckoutResult, CheckoutSubmission, ContentEntry, ContentJson, ContentMedia, ContentTypeSummary, CustomerAddress, CustomerAddressType, CustomerProfile, CustomerProfileUpdate, GetAttributeListOptions, GetCategoryListOptions, GetContentOptions, GetOrdersOptions, GetProductFiltersOptions, GetProductSeoEntriesOptions, GetProductsOptions, GetSearchSuggestionsOptions, GetStaticCatalogBootstrapOptions, GetStaticCatalogSnapshotOptions, GetWebsitePublicConfigOptions, Order, OrderItem, Product, ProductAttribute, ProductAvailability, ProductCategory, ProductContentBlock, ProductFilters, ProductMedia, ProductMediaKind, ProductOptionGroup, ProductOptionGroupMember, ProductPrice, ProductPriceType, ProductRelatedProduct, ProductSeoEntriesResult, ProductSeoEntry, ProductSortBy, ProductSpecification, ProductSpecificationFacet, ProductSpecificationField, ProductSpecificationFilterSelection, ProductSpecificationMeasure, ProductSpecificationOption, ProductSpecificationSection, ProductSubcategory, ProductVariant, ProductVariantLiveState, ProductVariantPricing, PublicOrder, PublicOrderDeliverySummary, PublicOrderItem, PublicOrderLookupInput, PublicOrderPaymentSummary, ResolvedWebsitePublicConfig, SearchSuggestion, StartGuestCheckoutInput, StaticCatalogBootstrap, StaticCatalogSnapshot, VariantAttribute, WaitForPublicOrderPaymentInput, WebsiteBrandingMedia, WebsiteBrandingPublicConfig, WebsiteCampaignCaptureContact, WebsiteCampaignCaptureInput, WebsiteCampaignCaptureResult, WebsiteCampaignCaptureSource, WebsiteCheckoutAddress, WebsiteCheckoutItem, WebsiteCouponActionResult, WebsiteDeliveryOption, WebsiteDepartmentOption, WebsiteFreeShippingProgress, WebsiteFulfillmentFamily, WebsiteGuestContact, WebsiteLegalPublicConfig, WebsiteLocationOptions, WebsiteMunicipalityOption, WebsitePaymentMethod, WebsitePaymentMode, WebsitePaymentOption, WebsitePaymentOptionMethod, WebsitePaymentSessionResult, WebsitePickupInfo, WebsitePublicConfig, WebsiteShippingPolicy, WebsiteShippingQuote, } from "./types";
+export type { AccessTokenProvider, AttributeFilter, BacanoClientConfig, BacanoClientContext, Brand, Cart, CartItem, CatalogAttributeList, CatalogAttributeListFilters, CatalogAttributeListItem, CatalogAttributeListValue, CatalogCategoryList, CatalogCategoryListItem, CatalogCategoryListItemSourceType, CheckoutResult, CheckoutSubmission, ContentEntry, ContentJson, ContentMedia, ContentTypeSummary, CustomerAddress, CustomerAddressType, CustomerProfile, CustomerProfileUpdate, GetAttributeListOptions, GetCategoryListOptions, GetContentOptions, GetOrdersOptions, GetProductFiltersOptions, GetProductSeoEntriesOptions, GetProductsOptions, GetSearchSuggestionsOptions, GetStaticCatalogBootstrapOptions, GetStaticCatalogSnapshotOptions, GetWebsitePublicConfigOptions, Order, OrderItem, Product, ProductAttribute, ProductAvailability, ProductCategory, ProductContentBlock, ProductFilters, ProductMedia, ProductMediaKind, ProductOptionGroup, ProductOptionGroupMember, ProductPrice, ProductPriceType, ProductRelatedProduct, ProductSeoEntriesResult, ProductSeoEntry, ProductSortBy, ProductSpecification, ProductSpecificationFacet, ProductSpecificationField, ProductSpecificationFilterSelection, ProductSpecificationMeasure, ProductSpecificationOption, ProductSpecificationSection, ProductSubcategory, ProductVariant, ProductVariantLiveState, ProductVariantPricing, PublicOrder, PublicOrderDeliverySummary, PublicOrderItem, PublicOrderLookupInput, PublicOrderPaymentSummary, ResolvedWebsitePublicConfig, SearchSuggestion, StartGuestCheckoutInput, StaticCatalogBootstrap, StaticCatalogSnapshot, VariantAttribute, WaitForPublicOrderPaymentInput, WebsiteBrandingMedia, WebsiteBrandingPublicConfig, WebsiteCampaignCaptureContact, WebsiteCampaignCaptureInput, WebsiteCampaignCaptureResult, WebsiteCampaignCaptureSource, WebsiteCheckoutAddress, WebsiteCheckoutItem, WebsiteCouponActionResult, WebsiteDeliveryOption, WebsiteDepartmentOption, WebsiteFormAction, WebsiteFormDefinition, WebsiteFormField, WebsiteFormFieldType, WebsiteFormOption, WebsiteFormOptionSource, WebsiteFormResponseInput, WebsiteFormResponseResult, WebsiteFormResponseSource, WebsiteFormResponseValue, WebsiteFormSection, WebsiteFormStatus, WebsiteFormStep, WebsiteFreeShippingProgress, WebsiteFulfillmentFamily, WebsiteGuestContact, WebsiteLegalPublicConfig, WebsiteLocationOptions, WebsiteMunicipalityOption, WebsitePaymentMethod, WebsitePaymentMode, WebsitePaymentOption, WebsitePaymentOptionMethod, WebsitePaymentSessionResult, WebsitePickupInfo, WebsitePublicConfig, WebsitePublishedForm, WebsiteShippingPolicy, WebsiteShippingQuote, } from "./types";