@bacano/sdk 1.1.12 → 1.1.15

package/CONTENT_TYPE_MANAGEMENT.md

@@ -1,9 +1,10 @@
-# Gestión de tipos de Content para agentes
+# Gestión segura de Content para agentes
 
 `@bacano/sdk/content-management` permite que una herramienta administrativa o
-un agente autorizado consulte, cree y mantenga **tipos y componentes** de
-Bacano Content. No permite administrar entradas, productos, ventas, clientes ni
-ningún otro dato de la empresa.
+un agente autorizado consulte y mantenga **tipos, componentes, grupos, listas
+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
@@ -13,17 +14,34 @@ dentro del bundle del sitio web.
 
 1. En Bacano, abre **Sitios web → Contenido → Tipos** o **Componentes**.
 2. Selecciona **Conectar agente**.
-3. Elige 15, 30 o 60 minutos y genera el acceso.
+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, pertenece a una sola empresa y solo contiene el alcance
-`content_types:manage`. Cada petición vuelve a comprobar que el usuario que lo
-generó continúa vinculado a la empresa y conserva `websites.manage`. Al vencer
-o perder ese permiso deja de funcionar.
+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`: 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.
 
+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
@@ -35,7 +53,7 @@ const content = createContentManagementClient({
 });
 
 const context = await content.getContext();
-console.log(context.companyId, context.expiresAt);
+console.log(context.companyId, context.scopes, context.expiresAt);
 ```
 
 El cliente ofrece:
@@ -47,6 +65,77 @@ El cliente ofrece:
 - `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)`.
+- `listMedia(filters)` y `uploadImage(input)` para reutilizar o cargar imágenes
+  cuando el acceso incluya `content_media:upload`.
+
+## 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
 
@@ -71,13 +160,13 @@ como una eliminación estructural y puede requerir
 
 ```ts
 await content.createType({
-  key: "cta_button",
+  key: "boton_llamada_accion",
   name: "Botón de llamada a la acción",
   kind: "component",
   status: "draft",
   fields: [
     {
-      key: "label",
+      key: "texto",
       label: "Texto",
       type: "text",
       required: true,
@@ -85,7 +174,7 @@ await content.createType({
       settings: { isVisible: true, maxLength: 80 },
     },
     {
-      key: "url",
+      key: "enlace",
       label: "Enlace",
       type: "link",
       required: true,
@@ -96,38 +185,38 @@ await content.createType({
 });
 
 await content.createType({
-  key: "home_hero",
+  key: "hero_inicio",
   name: "Hero del inicio",
   kind: "entry",
   status: "draft",
   usages: ["website_content"],
-  sections: [{ key: "content", title: "Contenido", sortOrder: 1 }],
+  sections: [{ key: "contenido", title: "Contenido", sortOrder: 1 }],
   fields: [
     {
-      key: "title",
+      key: "titulo",
       label: "Título",
       type: "text",
       required: true,
       sortOrder: 1,
-      sectionKey: "content",
+      sectionKey: "contenido",
       settings: { isVisible: true, maxLength: 120 },
     },
     {
-      key: "actions",
+      key: "acciones",
       label: "Acciones",
       type: "repeater",
       required: false,
       sortOrder: 2,
-      sectionKey: "content",
+      sectionKey: "contenido",
       settings: { isVisible: true, minRows: 0, maxRows: 3 },
       children: [
         {
-          key: "button",
+          key: "boton",
           label: "Botón",
           type: "component",
           required: true,
           sortOrder: 1,
-          componentKey: "cta_button",
+          componentKey: "boton_llamada_accion",
           settings: { isVisible: true },
         },
       ],
@@ -166,10 +255,10 @@ otros usos editoriales son `website_content` y `product_additional`.
 ## Ciclo de vida
 
 ```ts
-const preview = await content.inspectLifecycle("home_hero", "delete");
+const preview = await content.inspectLifecycle("hero_inicio", "delete");
 
 if (preview.allowed && userConfirmed) {
-  await content.applyLifecycle("home_hero", "delete");
+  await content.applyLifecycle("hero_inicio", "delete");
 }
 ```
 
@@ -178,15 +267,181 @@ 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` 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.
+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.
+
+## 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
+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.
+- 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 crea ni modifica entradas de Content.
-- No carga archivos ni media.
-- No crea listas de opciones.
+- 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.
 
 El resultado esperado del flujo Figma es: el agente propone el blueprint, el
-usuario habilita el acceso temporal, el agente crea o ajusta los tipos y
-componentes aprobados, y el equipo editorial completa las entradas desde
-Bacano.
+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,20 +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 tipos de Content para agentes
+### Gestión de Bacano Content para agentes
 
-Un agente autorizado puede consultar, crear y mantener tipos y componentes con
-el entrypoint administrativo `@bacano/sdk/content-management`. El acceso se
-genera temporalmente desde Bacano, está limitado a una empresa y nunca debe
-incluirse en el storefront:
+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, referencias,
-cambios destructivos y límites de seguridad.
+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
 
@@ -62,8 +66,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
@@ -82,10 +86,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. Las entradas reales continúan
-creándose desde Bacano. Con autorización temporal, la skill puede crear o
-ajustar tipos y componentes mediante el entrypoint administrativo oficial; 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: