@bacano/sdk 1.1.15 → 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-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;