@bacano/sdk 1.1.10 → 1.1.13

package/CONTENT_TYPE_MANAGEMENT.md

@@ -0,0 +1,401 @@
+# Gestión segura de Content para agentes
+
+`@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.
+
+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
+dentro del bundle del sitio web.
+
+## Activar un acceso temporal
+
+1. En Bacano, abre **Sitios web → Contenido → Tipos** o **Componentes**.
+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.
+
+El token está firmado con un secreto exclusivo, pertenece a una sola empresa y
+usuario y está respaldado por una concesión revocable. Cada petición comprueba
+la firma, vigencia, concesión, scopes exactos y que el usuario continúa
+vinculado a la empresa con `websites.manage`. Al vencer, revocarse o perder ese
+permiso deja de funcionar.
+
+Scopes disponibles:
+
+- `content_types:manage`: tipos, componentes, listas de opciones, referencias y
+  sus ciclos de vida.
+- `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.
+
+No guardes el token en Git, Figma, Content, logs, variables públicas ni archivos
+que se empaqueten con el storefront.
+
+Para desplegar Bacano, la API requiere
+`CONTENT_MANAGEMENT_TOKEN_SECRET`: un secreto aleatorio de al menos 32
+caracteres, exclusivo de esta capacidad y distinto de `API_SECRET`, JWT y los
+secretos de Hasura. Debe configurarse como secreto del entorno; nunca se entrega
+al agente. Rotarlo invalida inmediatamente todos los accesos temporales activos.
+
+## Crear el cliente
+
+```ts
+import { createContentManagementClient } from "@bacano/sdk/content-management";
+
+const content = createContentManagementClient({
+  apiUrl: process.env.BACANO_API_URL!,
+  accessToken: process.env.BACANO_CONTENT_ACCESS_TOKEN!,
+});
+
+const context = await content.getContext();
+console.log(context.companyId, context.scopes, context.expiresAt);
+```
+
+El cliente ofrece:
+
+- `getContext()` para confirmar empresa, alcance y vencimiento.
+- `getReferences()` para consultar categorías, subcategorías, listas de opciones
+  y unidades de medida válidas.
+- `listTypes()` y `getType(idOrKey)`.
+- `createType(input)` y `updateType(idOrKey, input)`.
+- `inspectLifecycle(idOrKey, operation)`.
+- `applyLifecycle(idOrKey, operation)`.
+- `listEntries(filters)`, `getEntry(idOrKey, locale?)`.
+- `createEntry(input)` y `updateEntry(idOrKey, input)`.
+- `inspectEntryLifecycle(idOrKey, operation)`.
+- `applyEntryLifecycle(idOrKey, operation)`.
+- `listGroups()`, `getGroup(idOrKey)`, `createGroup(input)` y
+  `updateGroup(idOrKey, input)`.
+- `inspectGroupLifecycle(idOrKey, operation)` y
+  `applyGroupLifecycle(idOrKey, operation)`.
+- `listOptionLists()`, `getOptionList(idOrKey)`, `createOptionList(input)` y
+  `updateOptionList(idOrKey, input)`.
+- `inspectOptionListLifecycle(idOrKey, operation)` y
+  `applyOptionListLifecycle(idOrKey, operation)`.
+
+## Idioma, nombres y keys
+
+Antes de proponer una estructura, resolver su idioma en este orden:
+
+1. El idioma solicitado expresamente por el usuario.
+2. La convención predominante del proyecto existente.
+3. El idioma principal del website.
+4. Si todavía existe una ambigüedad material, preguntar al usuario.
+
+Para un website en español, los nombres visibles y las keys nuevas se crean en
+español salvo instrucción contraria. Esta regla aplica a identificadores
+definidos por la empresa; los valores reservados del SDK como `entry`,
+`component`, `draft`, `website_content`, `text` o `repeater` no se traducen ni
+se reemplazan por valores inventados.
+
+Usar estas convenciones:
+
+| Elemento | Convención | Ejemplo |
+| --- | --- | --- |
+| Nombre visible | Lenguaje natural, con tildes | `Preguntas frecuentes` |
+| Key de tipo, componente, sección o campo | `snake_case`, sin tildes | `preguntas_frecuentes` |
+| Key o slug público de una entrada | `kebab-case`, sin tildes | `preguntas-frecuentes-inicio` |
+
+Las keys deben describir el significado del contenido, no detalles accidentales
+de su implementación visual. Preferir `titulo`, `descripcion`,
+`imagen_principal`, `enlace_contacto`, `preguntas`, `planes` o `pasos`. Evitar
+identificadores opacos como `data`, `content`, `items`, `field1`,
+`step1_title` o `component_2` cuando existe un nombre semántico claro.
+
+Para elementos repetidos, modelar un repetible y, cuando corresponda, un
+componente semántico. Por ejemplo, usar `pasos` con un componente `paso` que
+contenga `titulo` y `descripcion`, en vez de crear `paso1_titulo`,
+`paso1_descripcion`, `paso2_titulo` y campos sucesivos.
+
+Antes de crear algo nuevo:
+
+1. Consultar `listTypes()` y `getReferences()`.
+2. Reutilizar una estructura solo cuando conserva el mismo significado y la
+   misma forma, no únicamente porque algunos campos coinciden.
+3. Dar un nombre neutral a una estructura reutilizable, por ejemplo
+   `seccion_preguntas_frecuentes`.
+4. Incluir el contexto en el nombre cuando la estructura sea realmente
+   exclusiva, por ejemplo `calculadora_eficiencia_inicio`.
+5. Evitar nombres demasiado genéricos como `contenido` y nombres que quedarían
+   engañosos al reutilizarse, como `contenedor_principal_servicios` para una
+   página de blog.
+
+Una key activa es un contrato con el storefront. Nunca traducir, regenerar ni
+renombrar automáticamente keys existentes. La convención de idioma aplica a
+estructuras nuevas; cambiar una key utilizada requiere tratarlo como una
+migración explícita y presentar su impacto. Tampoco crear sufijos como `_2` o
+`-2` sin investigar primero el identificador existente.
+
+Antes de ejecutar `createType()`, presentar al usuario el nombre, key, idioma,
+uso, campos, componentes y decisión de creación o reutilización. Corregir
+mezclas de idiomas y errores ortográficos antes de materializar el blueprint.
+
+## Flujo seguro para un agente
+
+1. Ejecutar `getContext()` y confirmar la empresa con el usuario.
+2. Ejecutar `listTypes()` y `getReferences()` antes de proponer cambios.
+3. Reutilizar tipos, componentes, listas y keys existentes cuando correspondan.
+4. Crear primero los componentes que serán referenciados por otros tipos.
+5. Crear o actualizar en `draft`.
+6. Volver a consultar el tipo y presentar un resumen del resultado.
+7. Activarlo únicamente cuando el usuario haya aprobado la estructura.
+8. Para archivar, restaurar o eliminar, ejecutar primero
+   `inspectLifecycle()` y mostrar dependencias y bloqueos.
+9. Ejecutar `applyLifecycle()` solo después de una confirmación explícita.
+
+`updateType()` reemplaza la definición completa. Antes de usarlo debes obtener
+el tipo con `getType()`, conservar los IDs de campos existentes y enviar todos
+los campos y secciones que deban permanecer. La omisión de un campo se interpreta
+como una eliminación estructural y puede requerir
+`confirmDestructiveChanges: true`.
+
+## Ejemplo: componente y tipo editorial
+
+```ts
+await content.createType({
+  key: "boton_llamada_accion",
+  name: "Botón de llamada a la acción",
+  kind: "component",
+  status: "draft",
+  fields: [
+    {
+      key: "texto",
+      label: "Texto",
+      type: "text",
+      required: true,
+      sortOrder: 1,
+      settings: { isVisible: true, maxLength: 80 },
+    },
+    {
+      key: "enlace",
+      label: "Enlace",
+      type: "link",
+      required: true,
+      sortOrder: 2,
+      settings: { isVisible: true },
+    },
+  ],
+});
+
+await content.createType({
+  key: "hero_inicio",
+  name: "Hero del inicio",
+  kind: "entry",
+  status: "draft",
+  usages: ["website_content"],
+  sections: [{ key: "contenido", title: "Contenido", sortOrder: 1 }],
+  fields: [
+    {
+      key: "titulo",
+      label: "Título",
+      type: "text",
+      required: true,
+      sortOrder: 1,
+      sectionKey: "contenido",
+      settings: { isVisible: true, maxLength: 120 },
+    },
+    {
+      key: "acciones",
+      label: "Acciones",
+      type: "repeater",
+      required: false,
+      sortOrder: 2,
+      sectionKey: "contenido",
+      settings: { isVisible: true, minRows: 0, maxRows: 3 },
+      children: [
+        {
+          key: "boton",
+          label: "Botón",
+          type: "component",
+          required: true,
+          sortOrder: 1,
+          componentKey: "boton_llamada_accion",
+          settings: { isVisible: true },
+        },
+      ],
+    },
+  ],
+});
+```
+
+## Ajustes de campos
+
+Todos los campos aceptan `helpText`, `defaultValue`, `isPrivate` e
+`isVisible`. Usa además los ajustes correspondientes al tipo:
+
+| Tipo | Ajustes principales |
+| --- | --- |
+| `text`, `textarea`, `slug` | `minLength`, `maxLength`, `pattern` |
+| `rich_text`, `rich_text_full` | `richTextMode` |
+| `media` | `mediaMultiple`, `acceptedMediaKinds` |
+| `date` | `dateMode`: `date` o `datetime` |
+| `number` | `min`, `max`, `step`, `precision` |
+| `measure` | `measureDimensionCode`, `measureAllowedUnitCodes`, `measurePublicUnitCode` |
+| `select` | `selectSource`, `selectOptions`, `selectSourceKey`, `selectMultiple` |
+| `reference` | `referenceType`, `referenceContentTypeKey`, `referenceMultiple` |
+| `repeater` | `minRows`, `maxRows` y `children` |
+| `component` | `componentKey` |
+
+Para una lista administrable usa `selectSource: "option_list"` y una key
+devuelta por `getReferences().optionLists`. Para medidas usa exclusivamente los
+códigos devueltos por `getReferences().measureDimensions`; no inventes unidades.
+
+Una ficha técnica usa `usages: ["product_specification"]` y al menos un alcance
+en `specificationScopes`. Sus campos técnicos pueden declarar
+`isFilterable: true` únicamente cuando las reglas de Bacano lo permitan. Los
+otros usos editoriales son `website_content` y `product_additional`.
+
+## Ciclo de vida
+
+```ts
+const preview = await content.inspectLifecycle("hero_inicio", "delete");
+
+if (preview.allowed && userConfirmed) {
+  await content.applyLifecycle("hero_inicio", "delete");
+}
+```
+
+Nunca ignores `dependencies`, `allowed` o `errors`. Archivar es preferible a
+eliminar cuando existe contenido histórico. El backend aplica las mismas reglas
+de dependencias, keys, componentes, secciones y cambios destructivos que el
+backoffice; el SDK no crea un camino alterno.
+
+## Entradas
+
+Antes de crear una entrada, confirma que su tipo existe y que la estructura
+aprobada ya está activa. Las entradas nacen en `draft` salvo que el usuario haya
+concedido explícitamente `content_entries:publish`.
+
+```ts
+const existing = await content.listEntries({
+  contentType: "hero_inicio",
+  locale: "es-CO",
+  limit: 100,
+});
+
+const current = existing.entries.find(
+  (entry) => entry.key === "hero-principal-inicio",
+);
+
+if (!current) {
+  await content.createEntry({
+    contentType: "hero_inicio",
+    key: "hero-principal-inicio",
+    name: "Hero principal del inicio",
+    locale: "es-CO",
+    status: "draft",
+    content: {
+      titulo: "Encuentra lo mejor para cada etapa",
+      descripcion: "Compra productos seleccionados para tu familia.",
+    },
+  });
+} else {
+  await content.updateEntry(current.id, {
+    contentType: current.contentType.id,
+    key: current.key,
+    name: current.name,
+    locale: current.locale,
+    status: "draft",
+    content: {
+      ...current.content,
+      titulo: "Encuentra lo mejor para cada etapa",
+    },
+    expectedUpdatedAt: current.updatedAt,
+  });
+}
+```
+
+Reglas obligatorias:
+
+1. Inventariar por tipo, key y locale antes de crear; nunca fusionar por nombre.
+2. Usar `expectedUpdatedAt` al actualizar. Un conflicto exige volver a consultar
+   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.
+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.
+7. Inspeccionar el ciclo de vida antes de archivar, restaurar o eliminar.
+
+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.
+
+## Grupos y listas de opciones
+
+Los grupos organizan entradas y usan el scope `content_entries:manage`. Las
+listas proporcionan valores controlados para campos `select`, usan
+`content_types:manage` y conservan sus relaciones padre-hijo.
+
+```ts
+const group = await content.createGroup({
+  key: "pagina-principal",
+  name: "Página principal",
+  status: "active",
+});
+
+const materials = await content.createOptionList({
+  key: "materiales",
+  name: "Materiales",
+  status: "draft",
+  isExtensible: false,
+  items: [
+    { value: "algodon", label: "Algodón", sortOrder: 1 },
+    { value: "lino", label: "Lino", sortOrder: 2 },
+  ],
+});
+
+await content.updateOptionList(materials.id, {
+  key: materials.key,
+  name: materials.name,
+  status: "active",
+  isExtensible: materials.isExtensible,
+  items: materials.items.map((item) => ({
+    id: item.id,
+    value: item.value,
+    label: item.label,
+    parentItemId: item.parentItemId,
+    sortOrder: item.sortOrder,
+    isActive: item.isActive,
+    metadata: item.metadata,
+  })),
+});
+```
+
+`updateGroup()` y `updateOptionList()` reciben el documento completo que debe
+permanecer. Las keys existentes son inmutables. Para retirar elementos,
+archivar, restaurar o eliminar, primero usa la operación `inspect*Lifecycle()`.
+El backend bloquea desactivar o retirar opciones que todavía usan listas
+dependientes y exige `confirmDestructiveChanges` cuando corresponde; nunca
+omitas opciones existentes por accidente en una actualización.
+
+## Seguridad y auditoría
+
+- El `companyId` y el usuario provienen del token; no se aceptan desde el body.
+- Cada consulta y mutación está filtrada por la empresa firmada.
+- UUIDs o keys de otra empresa responden como inexistentes y no se modifican.
+- Las concesiones pueden revocarse individualmente desde Bacano.
+- 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.
+- 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.
+- 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.
+
+El resultado esperado del flujo Figma es: el agente propone el blueprint, el
+usuario habilita únicamente los scopes necesarios, el agente crea o ajusta la
+estructura y prepara entradas en borrador, y una persona revisa antes de
+publicar.

package/README.md

@@ -21,6 +21,24 @@ 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
+
+Un agente autorizado puede consultar y mantener tipos, componentes, grupos,
+listas de opciones y entradas 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:
+
+```ts
+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.
+
 ### Auditoría del storefront
 
 El SDK incluye la skill oficial `bacano-web`. Instalarla al iniciar un
@@ -47,8 +65,8 @@ el usuario o agente invoca la skill.
 ### Implementación desde Figma
 
 El SDK también incluye `bacano-figma-web`, la skill oficial para convertir un
-diseño Figma en una web informativa o tienda que conserve el cascarón, Static
-First y contratos públicos de Bacano:
+diseño Figma en una web informativa, tienda o sitio híbrido que conserve el
+cascarón, Static First y contratos públicos de Bacano:
 
 ```bash
 pnpm exec bacano-figma-web install --agent all
@@ -67,8 +85,11 @@ la presencia del token REST. El OAuth del MCP remoto debe confirmarse dentro del
 agente con las herramientas de Figma. La extracción se conserva como snapshot
 normalizado. Cuando el equipo de Content y desarrollo trabajan en tiempos
 distintos, la skill genera un blueprint de entrega y permite fixtures locales
-con el mismo contrato de los componentes. Los tipos y entradas reales se crean
-desde Bacano; un fixture activo bloquea la aprobación de producción.
+con el mismo contrato de los componentes. Con autorización temporal y scopes
+explícitos, puede crear o ajustar tipos, componentes, grupos, listas y entradas
+mediante el entrypoint administrativo oficial. Las entradas nacen en borrador;
+publicar exige permiso y aprobación humana. Un fixture activo en producción
+bloquea la aprobación del sitio.
 
 El snapshot puede validarse con: