@bacano/sdk 1.1.18 → 1.1.19

package/CONTENT_TYPE_MANAGEMENT.md

@@ -2,7 +2,8 @@
 
 `@bacano/sdk/content-management` permite que una herramienta administrativa o
 un agente autorizado consulte y mantenga **tipos, componentes, grupos, listas
-de opciones, entradas e imágenes** de Bacano Content. Cada capacidad requiere
+de opciones, entradas e imágenes** de Bacano Content, y **formularios web**.
+Cada capacidad requiere
 un permiso explícito. El acceso no autoriza productos, ventas, clientes,
 configuración general, GraphQL, SQL ni acceso directo a Storage.
 
@@ -12,7 +13,7 @@ dentro del bundle del sitio web.
 
 ## Activar un acceso temporal
 
-1. En Bacano, abre **Sitios web → Contenido → Tipos** o **Componentes**.
+1. En Bacano, abre **Sitios web → Contenido → Tipos**, **Componentes** o **Formularios**.
 2. Selecciona **Conectar agente**.
 3. Elige el alcance, 15, 30 o 60 minutos y genera el acceso.
 4. Copia el token al entorno local del agente.
@@ -32,6 +33,15 @@ Scopes disponibles:
   también `content_entries:manage`.
 - `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.
+- `forms:manage`: consultar sitios y listas disponibles para formularios,
+  inventariar formularios y crear o reemplazar sus borradores.
+- `forms:publish`: publicar, pausar, reactivar o archivar formularios. Requiere
+  `forms:manage`. También se exige para cambiar notificaciones de formularios
+  que ya fueron publicados, porque afectan envíos en curso.
+
+Los permisos de Content no conceden acceso a formularios ni viceversa. Los
+tokens existentes no se amplían; solicita uno nuevo con el alcance necesario.
+Estos permisos no permiten leer respuestas, datos personales, leads ni métricas.
 
 No guardes el token en Git, Figma, Content, logs, variables públicas ni archivos
 que se empaqueten con el storefront.
@@ -432,6 +442,74 @@ omitas opciones existentes por accidente en una actualización.
 - Los tokens v2 no son compatibles con tokens anteriores y tienen como máximo
   60 minutos de vigencia.
 
+## Formularios: misma definición en el agente, el ERP y el storefront
+
+No modeles un formulario como un tipo de Content ni mantengas una copia de sus
+campos en el frontend. Usa el mismo cliente administrativo con `forms:manage`:
+
+1. `getContext()` confirma empresa, scopes y vencimiento.
+2. `getFormReferences()` devuelve los sitios de esa empresa y las Listas de
+   Content activas, con sus pares `value` / `label`.
+3. `listForms({ websiteId, key, limit, offset })` inventaría antes de crear.
+   Las keys son únicas por sitio, no por empresa. Pagina hasta alcanzar `total`.
+4. Presenta al usuario sitio, key, campos, acción y mensajes antes de crear.
+5. `createForm(input)` crea exclusivamente un borrador.
+6. `getForm(formId)` consulta la definición completa y su `updatedAt`.
+7. `updateForm(formId, { ...input, expectedUpdatedAt })` reemplaza el borrador
+   completo. Conserva los campos que deben permanecer; no cambia key ni sitio.
+8. Solo con aprobación humana y `forms:publish`, usa `publishForm(formId,
+   { expectedUpdatedAt })`. Crea una versión inmutable que consume el SDK público.
+
+```ts
+const { websites, optionLists } = await content.getFormReferences();
+// Elegir y confirmar con el usuario un websiteId devuelto por websites.
+const form = await content.createForm({
+  websiteId,
+  key: "solicitar-informacion",
+  name: "Solicitar información",
+  action: "CAPTURE_LEAD",
+  definition: {
+    schemaVersion: 1,
+    submitLabel: "Enviar solicitud",
+    successMessage: "Recibimos tu solicitud.",
+    unavailableMessage: "Este formulario no está disponible.",
+    fields: [
+      { key: "correo", label: "Correo electrónico", type: "email", required: true },
+      {
+        key: "intereses", label: "¿Qué te interesa?", type: "multi_select", required: true,
+        optionSource: { kind: "INLINE", options: [
+          { value: "sitio_web", label: "Sitio web" },
+          { value: "tienda_virtual", label: "Tienda virtual" },
+        ] },
+      },
+    ],
+    sections: [],
+    steps: [],
+  },
+});
+// Tras revisar y aprobar; requiere forms:publish:
+await content.publishForm(form.id, { expectedUpdatedAt: form.updatedAt });
+```
+
+Las opciones `select`, `radio` y `multi_select` usan pares `value` / `label`
+o `optionSource: { kind: "CONTENT_LIST", listKey }`. Reutiliza únicamente una
+lista activa de `getFormReferences()`; administrarla exige el permiso separado
+de Content. Los tipos `email` y `phone` conservan la semántica de contacto.
+`CAPTURE_LEAD` utiliza la resolución de identidad ya existente: no llames además
+a la captura de campañas ni crees otro lead desde el agente.
+
+`changeFormStatus(formId, { status, expectedUpdatedAt })` acepta `ACTIVE`,
+`PAUSED` o `ARCHIVED`, con aprobación humana. Activar o pausar requiere una
+versión publicada; archivar es terminal en el flujo actual. No hay borrado ni
+restauración por este acceso.
+
+Ante `WEBSITE_FORM_REVISION_CONFLICT` (HTTP 409), vuelve a consultar y presenta
+las diferencias; nunca reintentes automáticamente reemplazando la revisión.
+Editar un borrador no publica su estructura: la versión pública anterior sigue
+vigente hasta publicar. Las respuestas y sus snapshots no se reescriben.
+Usa `BacanoForm` o `client.forms` con la key publicada y el mismo website,
+siguiendo `STOREFRONT_FORMS.md`. El token temporal jamás entra en ese bundle.
+
 ## Límites de esta versión
 
 - La carga administrativa solo admite imágenes raster JPEG, PNG y WebP. SVG,

package/README.md

@@ -21,10 +21,10 @@ React hooks are available from `@bacano/sdk/react` and require `react >= 18`
 as a peer dependency. The core client has no runtime dependencies and works
 without React.
 
-### Gestión de Bacano Content para agentes
+### Gestión de Content y formularios para agentes
 
 Un agente autorizado puede consultar y mantener tipos, componentes, grupos,
-listas de opciones y entradas con el entrypoint administrativo
+listas de opciones, entradas y formularios con el entrypoint administrativo
 `@bacano/sdk/content-management`. Cada capacidad exige un scope explícito. El
 acceso se genera temporalmente desde Bacano, está limitado a una empresa y
 nunca debe incluirse en el storefront:
@@ -221,7 +221,7 @@ The public storefront remains static. Preview V1 never exposes drafts and
 automatically disables the SDK marketing runtime inside its tree. See
 [`STOREFRONT_PREVIEW.md`](./STOREFRONT_PREVIEW.md), the canonical contract for
 provider hierarchy, responsibilities, security, agent checklist, and the
-validated Baby Rex reference implementation.
+validated reference implementation.
 
 ---
 

package/STOREFRONT_FORMS.md

@@ -4,6 +4,12 @@ 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.
 
+Un agente puede crear y editar estas mismas definiciones desde
+`@bacano/sdk/content-management`, con el acceso temporal de **Conectar agente**.
+Lee la sección de formularios en `CONTENT_TYPE_MANAGEMENT.md`: `forms:manage`
+prepara borradores y `forms:publish` permite publicar con aprobación. Nunca
+incluyas ese cliente administrativo ni su token en el storefront público.
+
 ## Renderer oficial para React
 
 Monta un único `BacanoProvider` global y usa la key pública configurada en el ERP:

package/STOREFRONT_LEADS.md

@@ -50,7 +50,7 @@ if (!consent) return null;
 // Conserva esta clave en el estado del formulario mientras reintentas el envío.
 const idempotencyKey = crypto.randomUUID();
 const result = await client.marketing.captureLead({
-  campaignKey: "newsletter-baby-rex",
+  campaignKey: "newsletter-primavera",
   idempotencyKey,
   commercialConsent: true,
   contact: {

package/STOREFRONT_PREVIEW.md

@@ -227,6 +227,7 @@ export default function PreviewPage() {
 "use client";
 
 import { useSearchParams } from "next/navigation";
+import { useState } from "react";
 import {
   BacanoPreviewShell,
   interceptPreviewLink,
@@ -265,7 +266,11 @@ const loadRoute: PreviewRouteLoader<PreviewDocument> = async ({
 
 export function PreviewClient() {
   const searchParams = useSearchParams();
-  const route = normalizePreviewRoute(searchParams.get("route"));
+  // Initial value only. Held in state afterwards so `navigate` can change it
+  // without a reload; listen for `popstate` to keep the back button working.
+  const [route, setRoute] = useState(() =>
+    normalizePreviewRoute(searchParams.get("route")),
+  );
 
   return (
     <BacanoPreviewShell
@@ -274,9 +279,17 @@ export function PreviewClient() {
       loadRoute={loadRoute}
       isPreviewableRoute={(nextRoute) => previewable.has(nextRoute)}
       navigate={(nextRoute) => {
-        window.location.assign(
+        // pushState, not location.assign. A full navigation unmounts the
+        // provider, and its route cache lives in a ref on it — so assigning
+        // location throws away every already-loaded route and refetches the
+        // one you are navigating to. Keep the route in state and let the
+        // provider reload it in place.
+        window.history.pushState(
+          null,
+          "",
           `/vista-previa/?route=${encodeURIComponent(nextRoute)}`,
         );
+        setRoute(nextRoute);
       }}
       toolbar={{
         websiteName: "My store",
@@ -414,10 +427,10 @@ When the storefront follows this contract:
 The build still depends on whatever Bacano data the public static pages request
 at build time. Preview does not change or replace that build contract.
 
-## Validated reference implementation: Baby Rex
+## Validated reference implementation
 
-Baby Rex validated the official integration with `@bacano/sdk` `1.0.5` on
-2026-08-06. It uses one global `BacanoProvider`; `BacanoPreviewShell` consumes
+A customer storefront validated the official integration with `@bacano/sdk`
+`1.0.5` on 2026-08-06. It uses one global `BacanoProvider`; `BacanoPreviewShell` consumes
 that initialized client and the loader receives `{ route, force, client }`.
 
 The validated static production build generated all `417/417` pages. TypeScript,
@@ -435,7 +448,7 @@ The implementation removed these generic storefront responsibilities:
 - Pathname-based marketing suppression inside preview renderers once the SDK
   boundary covers them.
 
-Baby Rex retained these storefront-specific responsibilities:
+That storefront retained these storefront-specific responsibilities:
 
 - `/vista-previa/page.tsx` and its `noindex` metadata.
 - Sitemap exclusion.
@@ -445,9 +458,9 @@ Baby Rex retained these storefront-specific responsibilities:
   content-driven catalog sections.
 - `PreviewDocumentView` and all production renderers.
 - Storefront-specific skeleton, missing-content, and unsupported-route views.
-- The Next.js adapter that writes `?ruta={encodedRoute}`.
+- The Next.js adapter that writes `?route={encodedRoute}`.
 
-Baby Rex is the implementation reference for integration shape, not a source to
+It is the implementation reference for integration shape, not a source to
 copy blindly. Other storefronts keep their own route maps, Content keys,
 mappers, and visual components.
 

package/STOREFRONT_VOLUME_PRICING.md

@@ -124,7 +124,7 @@ confirmado.
 
 ## Prohibiciones
 
-- No calcular umbrales en Baby Rex ni en otro storefront.
+- No calcular umbrales en el storefront.
 - No seleccionar `WHOLESALE` directamente desde el navegador.
 - No enviar precios en operaciones de carrito o checkout.
 - No consultar Hasura ni tablas de precios mediante GraphQL directo.

package/content-management-types.d.ts

@@ -1,7 +1,8 @@
+import type { FormManagementClient } from "./form-management-types";
 export type ContentManagementTypeKind = "entry" | "component";
 export type ContentManagementTypeStatus = "draft" | "active" | "archived";
 export type ContentManagementTypeUsage = "website_content" | "product_additional" | "product_specification";
-export type ContentManagementScope = "content_types:manage" | "content_entries:manage" | "content_media:upload" | "content_entries:publish";
+export type ContentManagementScope = "content_types:manage" | "content_entries:manage" | "content_media:upload" | "content_entries:publish" | "forms:manage" | "forms:publish";
 export type ContentManagementFieldType = "boolean" | "component" | "date" | "link" | "measure" | "media" | "number" | "reference" | "repeater" | "rich_text" | "rich_text_full" | "select" | "slug" | "text" | "textarea";
 export interface ContentManagementChildFieldInput {
     id?: string | null;
@@ -65,7 +66,7 @@ export interface ContentManagementType extends Omit<ContentManagementTypeInput,
 export interface ContentManagementContext {
     companyId: string;
     /** @deprecated Use scopes to inspect the complete grant. */
-    scope: "content_types:manage";
+    scope: ContentManagementScope;
     scopes: ContentManagementScope[];
     expiresAt: string;
 }
@@ -259,7 +260,7 @@ export interface ContentManagementClientConfig {
     accessToken: string | ContentManagementAccessTokenProvider;
     fetch?: typeof fetch;
 }
-export interface ContentManagementClient {
+export interface ContentManagementClient extends FormManagementClient {
     getContext(): Promise<ContentManagementContext>;
     getReferences(): Promise<ContentManagementReferences>;
     listTypes(): Promise<ContentManagementType[]>;

package/content-management.cjs

@@ -24,6 +24,42 @@ __export(content_management_exports, {
   createContentManagementClient: () => createContentManagementClient
 });
 module.exports = __toCommonJS(content_management_exports);
+
+// libs/sdk/src/form-management.ts
+function createFormManagementMethods(request) {
+  const path = (id) => `/forms/${encodeURIComponent(id.trim())}`;
+  return {
+    getFormReferences: () => request("/forms/references"),
+    listForms: (input = {}) => {
+      const search = new URLSearchParams();
+      for (const key of ["websiteId", "key", "limit", "offset"]) {
+        if (input[key] !== void 0) search.set(key, String(input[key]));
+      }
+      return request(
+        `/forms${search.size ? `?${search}` : ""}`
+      );
+    },
+    getForm: (id) => request(path(id)),
+    createForm: (input) => request("/forms", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateForm: (id, input) => request(path(id), {
+      method: "PUT",
+      body: JSON.stringify(input)
+    }),
+    publishForm: (id, input) => request(`${path(id)}/publish`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    changeFormStatus: (id, input) => request(`${path(id)}/status`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    })
+  };
+}
+
+// libs/sdk/src/content-management.ts
 var ContentManagementError = class extends Error {
   code;
   status;
@@ -145,6 +181,7 @@ function createContentManagementClient(config) {
     }
   );
   return {
+    ...createFormManagementMethods(request),
     getContext: () => request("/context"),
     getReferences: () => request("/references"),
     listTypes: () => request("/types"),

package/content-management.d.ts

@@ -1,5 +1,6 @@
 import type { ContentManagementClient, ContentManagementClientConfig } from "./content-management-types";
 export * from "./content-management-types";
+export * from "./form-management-types";
 export declare class ContentManagementError extends Error {
     readonly code: string;
     readonly status: number;

package/content-management.js

@@ -1,3 +1,37 @@
+// libs/sdk/src/form-management.ts
+function createFormManagementMethods(request) {
+  const path = (id) => `/forms/${encodeURIComponent(id.trim())}`;
+  return {
+    getFormReferences: () => request("/forms/references"),
+    listForms: (input = {}) => {
+      const search = new URLSearchParams();
+      for (const key of ["websiteId", "key", "limit", "offset"]) {
+        if (input[key] !== void 0) search.set(key, String(input[key]));
+      }
+      return request(
+        `/forms${search.size ? `?${search}` : ""}`
+      );
+    },
+    getForm: (id) => request(path(id)),
+    createForm: (input) => request("/forms", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateForm: (id, input) => request(path(id), {
+      method: "PUT",
+      body: JSON.stringify(input)
+    }),
+    publishForm: (id, input) => request(`${path(id)}/publish`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    changeFormStatus: (id, input) => request(`${path(id)}/status`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    })
+  };
+}
+
 // libs/sdk/src/content-management.ts
 var ContentManagementError = class extends Error {
   code;
@@ -120,6 +154,7 @@ function createContentManagementClient(config) {
     }
   );
   return {
+    ...createFormManagementMethods(request),
     getContext: () => request("/context"),
     getReferences: () => request("/references"),
     listTypes: () => request("/types"),

package/form-management-types.d.ts

@@ -0,0 +1,62 @@
+import type { WebsiteFormAction, WebsiteFormDefinition } from "./types";
+export interface ManagedFormInput {
+    websiteId: string;
+    key: string;
+    name: string;
+    description?: string;
+    action?: WebsiteFormAction;
+    notifyByEmail?: boolean;
+    notificationRecipients?: string[];
+    definition: WebsiteFormDefinition;
+}
+export interface ManagedForm extends Required<ManagedFormInput> {
+    id: string;
+    companyId: string;
+    status: "DRAFT" | "ACTIVE" | "PAUSED" | "ARCHIVED";
+    publishedVersion: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ManagedFormListInput {
+    websiteId?: string;
+    key?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface ManagedFormList {
+    forms: ManagedForm[];
+    total: number;
+}
+export interface ManagedFormReferences {
+    websites: Array<{
+        id: string;
+        name: string;
+        slug: string;
+        isActive: boolean;
+    }>;
+    optionLists: Array<{
+        key: string;
+        name: string;
+        options: Array<{
+            value: string;
+            label: string;
+        }>;
+    }>;
+}
+export interface FormManagementClient {
+    getFormReferences(): Promise<ManagedFormReferences>;
+    listForms(input?: ManagedFormListInput): Promise<ManagedFormList>;
+    getForm(formId: string): Promise<ManagedForm>;
+    createForm(input: ManagedFormInput): Promise<ManagedForm>;
+    /** Replaces the full draft. Preserve existing fields and use the last read revision. */
+    updateForm(formId: string, input: ManagedFormInput & {
+        expectedUpdatedAt: string;
+    }): Promise<ManagedForm>;
+    publishForm(formId: string, input: {
+        expectedUpdatedAt: string;
+    }): Promise<ManagedForm>;
+    changeFormStatus(formId: string, input: {
+        status: "ACTIVE" | "PAUSED" | "ARCHIVED";
+        expectedUpdatedAt: string;
+    }): Promise<ManagedForm>;
+}

package/form-management.d.ts

@@ -0,0 +1,2 @@
+import type { FormManagementClient } from "./form-management-types";
+export declare function createFormManagementMethods(request: <T>(path: string, init?: RequestInit) => Promise<T>): FormManagementClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacano/sdk",
-  "version": "1.1.18",
+  "version": "1.1.19",
   "description": "TypeScript SDK for building websites on the Bacano ERP",
   "main": "./index.cjs",
   "module": "./index.js",

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

@@ -96,7 +96,7 @@ Figma, desde Bacano Content o desde ambas fuentes.
   entrada completa, nunca campos individuales. Conservar esta identidad al
   transformar Content en view models y seguir
   `STOREFRONT_CONTENT_LOCATOR.md`.
-- No alterar Baby Rex u otra referencia salvo que ese sea el proyecto indicado.
+- No alterar el storefront de referencia salvo que ese sea el proyecto indicado.
 
 Si Content todavía no existe, generar un blueprint de entrega y fixtures
 temporales fieles al contenido visible de Figma. Los fixtures deben usar el

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

@@ -11,6 +11,7 @@ Antes de crear campos o fixtures, asignar cada valor a una fuente:
 | Información | Fuente habitual |
 | --- | --- |
 | Títulos, textos, banners y bloques editoriales | Bacano Content |
+| Campos, opciones, pasos y validaciones de formularios | Formularios de Bacano; nunca tipos de Content |
 | Productos, variantes, precios y disponibilidad | Catálogo y live state del SDK |
 | Legal, branding y configuración del sitio | `publicConfig` |
 | Carrito, checkout, cliente y pedidos | Módulo correspondiente del SDK |
@@ -19,6 +20,12 @@ Antes de crear campos o fixtures, asignar cada valor a una fuente:
 No duplicar en Content información que ya tiene una fuente funcional. Un valor
 visible en Figma no implica que sea editorial.
 
+Para materializar un formulario del diseño, seguir `STOREFRONT_FORMS.md` y la
+sección de formularios de `CONTENT_TYPE_MANAGEMENT.md`. El cliente temporal
+admite `forms:manage` para crear/editar borradores y `forms:publish` para publicar
+con confirmación. Reutilizar la definición del ERP y sus pares value/label;
+no inventar un esquema paralelo. Los conflictos de revisión requieren releer.
+
 ## Modelar sin extremos
 
 No convertir una página extensa en un único tipo gigante ni crear un componente

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

@@ -3,6 +3,19 @@
 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.
 
+## Creación asistida y sincronización
+
+Si falta el formulario, proponer su definición y pedir el acceso temporal de
+**Conectar agente** en Formularios o Content. Leer `CONTENT_TYPE_MANAGEMENT.md`.
+Usar `createContentManagementClient` con `forms:manage`; inventariar sitios,
+listas y formularios antes de crear. Editar mediante `updateForm()` enviando
+el documento completo y `expectedUpdatedAt`. Los conflictos exigen releer,
+no sobreescribir. Publicar o retirar requiere `forms:publish` y confirmación.
+No duplicar las definiciones en Content, GraphQL, SQL ni en fixtures permanentes.
+El storefront consume la key y versión publicada usando el SDK público.
+El acceso administrativo no permite leer respuestas ni PII. `CAPTURE_LEAD`
+ya resuelve la identidad; no ejecutar una segunda captura por campaña.
+
 ## Implementación oficial
 
 - Clasificar formularios como `ACTIVA`, `INACTIVA` o `BLOQUEADA` en la matriz de