@bacano/sdk 1.1.13 → 1.1.17

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

@@ -77,7 +77,8 @@ pnpm exec bacano-figma-web validate-snapshot .bacano/designs/<proyecto>/manifest
 ## 4. Mapear a Bacano antes de programar
 
 Leer [references/bacano-mapping.md](references/bacano-mapping.md),
-[references/content-workflow.md](references/content-workflow.md) y
+[references/content-workflow.md](references/content-workflow.md),
+[references/content-media.md](references/content-media.md) y
 [references/implementation-quality.md](references/implementation-quality.md).
 Preparar una matriz ruta → frame → componente → fuente de datos → Content →
 responsive → preview → estado, y determinar si el trabajo comienza desde
@@ -103,7 +104,10 @@ blueprint, leer la sección de automatización de
 componentes, grupos, listas y entradas únicamente mediante el acceso temporal
 y los scopes oficiales. Inventariar esos recursos antes de crear otros y
 preparar entradas en borrador por defecto; la media permanece en el
-backoffice y publicar requiere permiso y aprobación explícitos.
+backoffice salvo que el usuario conceda `content_media:upload`. Con ese scope,
+buscar primero imágenes reutilizables y cargar bytes únicamente mediante
+`listMedia()` y `uploadImage()`; publicar requiere permiso y aprobación
+explícitos.
 
 Al proponer keys nuevas, resolver primero el idioma según
 `CONTENT_TYPE_MANAGEMENT.md`: instrucción explícita, convención existente y
@@ -129,7 +133,9 @@ lo pendiente cuando la revisión visual quede a cargo del usuario.
 
 No añadir paquetes, fuentes, iconos o assets si el proyecto ya ofrece un
 equivalente. Descargar assets mediante la fuente Figma autorizada; no incrustar
-URLs temporales ni construir transformaciones de Storage manualmente.
+URLs temporales ni construir transformaciones de Storage manualmente. La carga
+administrativa admite JPEG, PNG o WebP raster; video, documentos, SVG y
+animaciones continúan bajo revisión editorial en el backoffice.
 
 ## 6. Validar diseño y contrato
 

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

@@ -0,0 +1,57 @@
+# Imágenes de Content desde un agente
+
+Usar este flujo solo cuando `getContext().scopes` incluya
+`content_media:upload`. El token temporal continúa siendo administrativo: no se
+incluye en el storefront, Figma, archivos del proyecto, logs ni respuestas al
+usuario.
+
+## Orden obligatorio
+
+1. Clasificar el asset: hero desktop/mobile, card, galería, logo, decorativo u
+   otro uso editorial.
+2. Buscar en `listMedia()` con términos semánticos. Reutilizar únicamente cuando
+   sea el mismo asset, no solo una imagen parecida.
+3. Exportar desde la fuente Figma autorizada los bytes originales necesarios.
+4. Para imágenes informativas, preparar un nombre descriptivo y `altText`
+   contextual. No usar nombres de capas como `Frame 32` o `image_1`.
+5. Cargar con `uploadImage()`. Nunca usar GraphQL, URLs de Figma, base64 dentro
+   de una entrada ni endpoints directos de Nhost Storage.
+6. Guardar en Content el `fileId` devuelto y volver a consultar la entrada.
+7. Mantener en borrador hasta validar imagen, encuadre, responsive y texto
+   alternativo en contexto.
+
+```ts
+import { readFile } from "node:fs/promises";
+import { createContentManagementClient } from "@bacano/sdk/content-management";
+
+const content = createContentManagementClient({
+  apiUrl: process.env.BACANO_API_URL!,
+  accessToken: process.env.BACANO_CONTENT_ACCESS_TOKEN!,
+});
+
+const matches = await content.listMedia({ search: "hero juguetes" });
+const media = matches.items[0] ?? await content.uploadImage({
+  file: await readFile("./exports/hero-juguetes-desktop.png"),
+  fileName: "Hero juguetes para bebé desktop",
+  altText: "Niña jugando con bloques de colores",
+});
+
+console.log(media.fileId);
+```
+
+## Contrato de la primera versión
+
+- Admite JPEG, PNG y WebP raster no animado.
+- Máximo 10 MB de entrada y 100 megapíxeles.
+- Bacano valida bytes reales, corrige orientación y normaliza a WebP.
+- El nombre se convierte a un filename SEO seguro.
+- Los duplicados binarios normalizados se reutilizan dentro de la misma
+  empresa; nunca entre empresas.
+- SVG, GIF animado, video y documentos se cargan desde el backoffice.
+- El agente no reemplaza ni elimina físicamente media.
+- `altText` de biblioteca es fallback. El texto alternativo final pertenece al
+  uso dentro de la entrada; una imagen decorativa usa `alt=""` en ese contexto.
+
+Si el asset no cabe en este contrato, reportar `BLOQUEADO` y pedir que el equipo
+editorial lo prepare en la biblioteca. No convertirlo de forma improvisada ni
+introducir paquetes o servicios paralelos.

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

@@ -155,7 +155,9 @@ usuario autoriza que el agente materialice el blueprint, usar exclusivamente
 agente**. Confirmar la empresa y los scopes, inventariar primero, crear
 componentes antes de sus consumidores y trabajar inicialmente en borrador. La
 skill puede preparar entradas cuando el usuario conceda
-`content_entries:manage`; no carga media ni publica sin el scope específico.
+`content_entries:manage`. Si además se concede `content_media:upload`, debe
+buscar y cargar imágenes por el contrato descrito en
+[content-media.md](content-media.md). No publica sin el scope específico.
 
 ## 6. Cambio a Bacano real
 
@@ -189,7 +191,8 @@ escribir:
    locale; crear las faltantes en borrador y actualizar únicamente con
    `expectedUpdatedAt`.
 7. No fusionar por nombres, no usar HTML crudo y no relacionar URLs remotas. La
-   media debe existir en Bacano y pertenecer a la empresa autorizada.
+   media debe existir en Bacano y pertenecer a la empresa autorizada; resolver
+   su `fileId` mediante `listMedia()` o `uploadImage()`.
 8. Para archivar o eliminar tipos, entradas, grupos o listas, inspeccionar
    dependencias y confirmar nuevamente. Una actualización de lista debe enviar
    todos los elementos que deben permanecer, incluidos sus IDs existentes.
@@ -198,5 +201,5 @@ escribir:
 
 Nunca exponer el token en el navegador, commit, blueprint, salida de consola o
 chat. Nunca convertir el blueprint en una importación implícita ni usar GraphQL
-directo. La carga de media permanece bajo gestión editorial en Bacano hasta que
-exista el scope y endpoint administrativo oficial.
+directo. Sin `content_media:upload`, toda media permanece bajo gestión
+editorial en el backoffice.

package/skills/bacano-web/SKILL.md

@@ -51,6 +51,9 @@ de proponer cambios. Como mínimo revisar `STOREFRONT_LEGAL.md`,
 `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
 

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

@@ -0,0 +1,50 @@
+# 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`.
+- 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.
+- No afirmar que se creó un lead, se envió un correo 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.
+- 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,89 @@ 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. Storefronts should render it visually hidden and leave it empty. */
+    honeypot?: string;
+}
+export interface WebsiteFormResponseResult {
+    accepted: boolean;
+    responseId: string | null;
+    message: string;
+}
 export type ResolvedWebsitePublicConfig = WebsitePublicConfig & {
     branding: WebsiteBrandingPublicConfig;
     legal: WebsiteLegalPublicConfig;