@bacano/sdk 1.1.13 → 1.1.17

package/CONTENT_TYPE_MANAGEMENT.md

@@ -2,9 +2,9 @@
 
 `@bacano/sdk/content-management` permite que una herramienta administrativa o
 un agente autorizado consulte y mantenga **tipos, componentes, grupos, listas
-de opciones y entradas** de Bacano Content. Cada capacidad requiere un permiso explícito. El acceso no
-autoriza productos, ventas, clientes, configuración general, GraphQL, SQL ni
-Storage.
+de opciones, entradas e imágenes** de Bacano Content. Cada capacidad requiere
+un permiso explícito. El acceso no autoriza productos, ventas, clientes,
+configuración general, GraphQL, SQL ni acceso directo a Storage.
 
 Este contrato es independiente del cliente público del storefront. Debe usarse
 solo desde un proceso local o servidor confiable; nunca desde el navegador ni
@@ -30,8 +30,8 @@ Scopes disponibles:
 - `content_entries:manage`: grupos, entradas en borrador y sus ciclos de vida.
 - `content_entries:publish`: publicar y modificar contenido publicado; requiere
   también `content_entries:manage`.
-- `content_media:upload`: reservado para una fase posterior; no se concede
-  mientras la carga administrativa de media no esté implementada.
+- `content_media:upload`: consultar imágenes de la empresa y cargar JPEG, PNG o
+  WebP. Requiere también `content_entries:manage`; no permite borrar archivos.
 
 No guardes el token en Git, Figma, Content, logs, variables públicas ni archivos
 que se empaqueten con el storefront.
@@ -77,6 +77,8 @@ El cliente ofrece:
   `updateOptionList(idOrKey, input)`.
 - `inspectOptionListLifecycle(idOrKey, operation)` y
   `applyOptionListLifecycle(idOrKey, operation)`.
+- `listMedia(filters)` y `uploadImage(input)` para reutilizar o cargar imágenes
+  cuando el acceso incluya `content_media:upload`.
 
 ## Idioma, nombres y keys
 
@@ -317,8 +319,9 @@ Reglas obligatorias:
    y presentar el cambio; no se sobrescribe silenciosamente.
 3. Enviar el documento completo que debe permanecer. `updateEntry()` reemplaza
    el contenido de la entrada después de aplicar las validaciones oficiales.
-4. Reutilizar únicamente `fileId` ya existentes y pertenecientes a la misma
-   empresa. Este acceso no sube media ni acepta URLs arbitrarias.
+4. Reutilizar únicamente `fileId` pertenecientes a la misma empresa. Con
+   `content_media:upload`, resolverlos mediante `listMedia()` o
+   `uploadImage()`; nunca relacionar URLs arbitrarias.
 5. Rich text usa el JSON controlado por Bacano, nunca HTML crudo.
 6. Publicar, retirar o modificar una entrada publicada requiere
    `content_entries:publish` y aprobación humana explícita.
@@ -328,6 +331,45 @@ La API reutiliza el mismo servicio de guardado del backoffice: campos
 obligatorios, componentes anidados, repetibles, listas, referencias, rich text,
 media y pertenencia a la empresa se validan de forma autoritativa.
 
+## Imágenes
+
+Antes de cargar, busca por nombre o texto alternativo para reutilizar la
+biblioteca existente:
+
+```ts
+import { readFile } from "node:fs/promises";
+
+const existing = await content.listMedia({ search: "hero juguetes" });
+
+const hero = existing.items[0] ?? await content.uploadImage({
+  file: await readFile("./hero-juguetes.png"),
+  fileName: "Hero juguetes para bebé",
+  altText: "Niña jugando con juguetes educativos",
+});
+
+console.log(hero.fileId, hero.width, hero.height);
+```
+
+`uploadImage()` envía los bytes al endpoint administrativo de Bacano. El
+servidor comprueba el contenido real, corrige orientación, elimina metadatos no
+necesarios, normaliza a WebP y registra nombre, MIME, tamaño y dimensiones. El
+límite de entrada es 10 MB y 100 megapíxeles. No se admiten animaciones,
+archivos corruptos, SVG, video ni documentos en esta primera versión.
+
+El nombre entregado debe describir el asset; Bacano lo normaliza a un filename
+SEO seguro y agrega un sufijo corto para evitar colisiones. Un SHA-256 de los
+bytes WebP normalizados permite reutilizar duplicados dentro de la misma
+empresa. Nunca se deduplica entre empresas.
+
+El `altText` de la biblioteca es solo un fallback. Al asociar una imagen a una
+entrada, conserva el texto alternativo contextual que corresponda a ese uso;
+una misma imagen puede significar cosas distintas en dos secciones. Para una
+imagen decorativa el contenido final debe usar `alt=""`.
+
+El agente no puede reemplazar ni borrar físicamente media. Una edición genera
+otro asset y cambia explícitamente el `fileId` de la entrada. Esto evita romper
+productos, servicios, branding u otras entradas que todavía usen el archivo.
+
 ## Grupos y listas de opciones
 
 Los grupos organizan entradas y usan el scope `content_entries:manage`. Las
@@ -385,12 +427,16 @@ omitas opciones existentes por accidente en una actualización.
 - Emisión, revocación y mutaciones quedan en una auditoría inmutable sin guardar
   el bearer token ni el documento completo.
 - Las respuestas del endpoint usan `no-store`, límites de tamaño y rate limit.
+- Las cargas tienen un límite adicional por concesión; no aceptan importación
+  por URL ni exponen credenciales o endpoints internos de Storage.
 - Los tokens v2 no son compatibles con tokens anteriores y tienen como máximo
   60 minutos de vigencia.
 
 ## Límites de esta versión
 
-- No carga archivos ni crea media; puede relacionar media existente validada.
+- La carga administrativa solo admite imágenes raster JPEG, PNG y WebP. SVG,
+  animaciones, video y documentos continúan en el backoffice.
+- No elimina ni reemplaza físicamente archivos de la biblioteca.
 - No funciona desde el cliente público del storefront.
 - No acepta GraphQL directo ni credenciales administrativas permanentes.
 - No previsualiza borradores desde el storefront público.

package/README.md

@@ -34,10 +34,11 @@ import { createContentManagementClient } from "@bacano/sdk/content-management";
 ```
 
 Lee [`CONTENT_TYPE_MANAGEMENT.md`](./CONTENT_TYPE_MANAGEMENT.md) antes de usarlo.
-La guía contiene el flujo de autorización, contratos de campos y entradas,
-estados, referencias, cambios destructivos y límites de seguridad. La carga de
-media continúa en el backoffice hasta que exista un contrato administrativo
-oficial para ella.
+La guía contiene el flujo de autorización, contratos de campos, entradas y
+media, estados, referencias, cambios destructivos y límites de seguridad. Con
+el scope `content_media:upload`, un agente puede buscar imágenes existentes y
+cargar JPEG, PNG o WebP mediante el contrato oficial; Bacano valida los bytes,
+normaliza a WebP y registra el resultado en la biblioteca de la empresa.
 
 ### Auditoría del storefront
 
@@ -111,6 +112,12 @@ 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.
+
 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_FORMS.md

@@ -0,0 +1,147 @@
+# 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.
+
+## 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.
+- Una falla futura de correo, CRM o automatización no revierte la respuesta.
+- `CAPTURE_LEAD` se procesa en una fase posterior. Toda respuesta se conserva
+  primero y de forma independiente.
+
+## 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.
+- 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.
+- No prometer correo, lead, solicitud o automatización mientras la capacidad no
+  esté implementada y activa en Bacano.

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-management-types.d.ts

@@ -113,6 +113,35 @@ export interface ContentManagementEntryList {
     entries: ContentManagementEntry[];
     total: number;
 }
+export interface ContentManagementMedia {
+    id: string;
+    fileId: string;
+    name: string;
+    mediaKind: "image";
+    mimeType: string;
+    sizeBytes: number;
+    width: number | null;
+    height: number | null;
+    altText: string;
+    createdAt: string;
+}
+export interface ContentManagementMediaListInput {
+    search?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface ContentManagementMediaList {
+    items: ContentManagementMedia[];
+    total: number;
+}
+export interface ContentManagementImageUploadInput {
+    file: Blob | ArrayBuffer | Uint8Array;
+    fileName: string;
+    altText?: string;
+}
+export interface ContentManagementImageUploadResult extends ContentManagementMedia {
+    reused: boolean;
+}
 export interface ContentManagementReferences {
     categories: Array<{
         code: string;
@@ -245,6 +274,8 @@ export interface ContentManagementClient {
     updateEntry(identifier: string, input: ContentManagementEntryInput): Promise<ContentManagementEntry>;
     inspectEntryLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
     applyEntryLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
+    listMedia(input?: ContentManagementMediaListInput): Promise<ContentManagementMediaList>;
+    uploadImage(input: ContentManagementImageUploadInput): Promise<ContentManagementImageUploadResult>;
     listGroups(): Promise<ContentManagementGroup[]>;
     getGroup(identifier: string): Promise<ContentManagementGroup>;
     createGroup(input: ContentManagementGroupInput): Promise<ContentManagementGroup>;

package/content-management.cjs

@@ -68,6 +68,24 @@ function entryListPath(input = {}) {
   const query = search.toString();
   return query ? `/entries?${query}` : "/entries";
 }
+function mediaListPath(input = {}) {
+  const search = new URLSearchParams();
+  if (input.search) search.set("search", input.search);
+  if (input.limit !== void 0) search.set("limit", String(input.limit));
+  if (input.offset !== void 0) search.set("offset", String(input.offset));
+  const query = search.toString();
+  return query ? `/media?${query}` : "/media";
+}
+function uploadBody(file) {
+  if ("arrayBuffer" in file) return file;
+  if (file instanceof ArrayBuffer) return file;
+  const bytes = new Uint8Array(file.byteLength);
+  bytes.set(file);
+  return bytes.buffer;
+}
+function encodedHeader(value) {
+  return encodeURIComponent(value.trim());
+}
 function createContentManagementClient(config) {
   const apiUrl = normalizeApiUrl(config.apiUrl);
   const fetchImplementation = config.fetch ?? globalThis.fetch;
@@ -98,7 +116,7 @@ function createContentManagementClient(config) {
         headers: {
           Accept: "application/json",
           Authorization: `Bearer ${await getAccessToken()}`,
-          ...init?.body ? { "Content-Type": "application/json" } : {},
+          ...typeof init?.body === "string" ? { "Content-Type": "application/json" } : {},
           ...init?.headers
         }
       }
@@ -161,6 +179,26 @@ function createContentManagementClient(config) {
     ),
     inspectEntryLifecycle: (identifier, operation) => lifecycle("entries", identifier, operation, true),
     applyEntryLifecycle: (identifier, operation) => lifecycle("entries", identifier, operation, false),
+    listMedia: (input) => request(mediaListPath(input)),
+    uploadImage: (input) => {
+      const fileName = input.fileName.trim();
+      if (!fileName) {
+        throw new ContentManagementError({
+          message: "A descriptive image file name is required.",
+          code: "CONTENT_MEDIA_FILE_NAME_REQUIRED",
+          status: 0
+        });
+      }
+      return request("/media/images", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/octet-stream",
+          "X-Bacano-File-Name": encodedHeader(fileName),
+          ...input.altText ? { "X-Bacano-Alt-Text": encodedHeader(input.altText) } : {}
+        },
+        body: uploadBody(input.file)
+      });
+    },
     listGroups: () => request("/groups"),
     getGroup: (identifier) => request(
       `/groups/${encodeIdentifier(identifier)}`

package/content-management.js

@@ -43,6 +43,24 @@ function entryListPath(input = {}) {
   const query = search.toString();
   return query ? `/entries?${query}` : "/entries";
 }
+function mediaListPath(input = {}) {
+  const search = new URLSearchParams();
+  if (input.search) search.set("search", input.search);
+  if (input.limit !== void 0) search.set("limit", String(input.limit));
+  if (input.offset !== void 0) search.set("offset", String(input.offset));
+  const query = search.toString();
+  return query ? `/media?${query}` : "/media";
+}
+function uploadBody(file) {
+  if ("arrayBuffer" in file) return file;
+  if (file instanceof ArrayBuffer) return file;
+  const bytes = new Uint8Array(file.byteLength);
+  bytes.set(file);
+  return bytes.buffer;
+}
+function encodedHeader(value) {
+  return encodeURIComponent(value.trim());
+}
 function createContentManagementClient(config) {
   const apiUrl = normalizeApiUrl(config.apiUrl);
   const fetchImplementation = config.fetch ?? globalThis.fetch;
@@ -73,7 +91,7 @@ function createContentManagementClient(config) {
         headers: {
           Accept: "application/json",
           Authorization: `Bearer ${await getAccessToken()}`,
-          ...init?.body ? { "Content-Type": "application/json" } : {},
+          ...typeof init?.body === "string" ? { "Content-Type": "application/json" } : {},
           ...init?.headers
         }
       }
@@ -136,6 +154,26 @@ function createContentManagementClient(config) {
     ),
     inspectEntryLifecycle: (identifier, operation) => lifecycle("entries", identifier, operation, true),
     applyEntryLifecycle: (identifier, operation) => lifecycle("entries", identifier, operation, false),
+    listMedia: (input) => request(mediaListPath(input)),
+    uploadImage: (input) => {
+      const fileName = input.fileName.trim();
+      if (!fileName) {
+        throw new ContentManagementError({
+          message: "A descriptive image file name is required.",
+          code: "CONTENT_MEDIA_FILE_NAME_REQUIRED",
+          status: 0
+        });
+      }
+      return request("/media/images", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/octet-stream",
+          "X-Bacano-File-Name": encodedHeader(fileName),
+          ...input.altText ? { "X-Bacano-Alt-Text": encodedHeader(input.altText) } : {}
+        },
+        body: uploadBody(input.file)
+      });
+    },
     listGroups: () => request("/groups"),
     getGroup: (identifier) => request(
       `/groups/${encodeIdentifier(identifier)}`

package/index.cjs

@@ -66,10 +66,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 +6115,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 +6806,7 @@ function createBacanoClient(config) {
     config.websiteSlug,
     getContext
   );
+  const formsModule = createFormsModule(apiUrl, config.websiteSlug, getContext);
   return {
     async init() {
       if (context) return;
@@ -6693,6 +6859,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),