@bacano/sdk 1.1.12 → 1.1.15

package/content-management.js

@@ -33,6 +33,34 @@ function encodeIdentifier(identifier) {
   }
   return encodeURIComponent(normalized);
 }
+function entryListPath(input = {}) {
+  const search = new URLSearchParams();
+  if (input.contentType) search.set("contentType", input.contentType);
+  if (input.locale) search.set("locale", input.locale);
+  if (input.status) search.set("status", input.status);
+  if (input.limit !== void 0) search.set("limit", String(input.limit));
+  if (input.offset !== void 0) search.set("offset", String(input.offset));
+  const query = search.toString();
+  return query ? `/entries?${query}` : "/entries";
+}
+function mediaListPath(input = {}) {
+  const search = new URLSearchParams();
+  if (input.search) search.set("search", input.search);
+  if (input.limit !== void 0) search.set("limit", String(input.limit));
+  if (input.offset !== void 0) search.set("offset", String(input.offset));
+  const query = search.toString();
+  return query ? `/media?${query}` : "/media";
+}
+function uploadBody(file) {
+  if ("arrayBuffer" in file) return file;
+  if (file instanceof ArrayBuffer) return file;
+  const bytes = new Uint8Array(file.byteLength);
+  bytes.set(file);
+  return bytes.buffer;
+}
+function encodedHeader(value) {
+  return encodeURIComponent(value.trim());
+}
 function createContentManagementClient(config) {
   const apiUrl = normalizeApiUrl(config.apiUrl);
   const fetchImplementation = config.fetch ?? globalThis.fetch;
@@ -63,7 +91,7 @@ function createContentManagementClient(config) {
         headers: {
           Accept: "application/json",
           Authorization: `Bearer ${await getAccessToken()}`,
-          ...init?.body ? { "Content-Type": "application/json" } : {},
+          ...typeof init?.body === "string" ? { "Content-Type": "application/json" } : {},
           ...init?.headers
         }
       }
@@ -84,8 +112,8 @@ function createContentManagementClient(config) {
     }
     return payload.data;
   };
-  const lifecycle = (identifier, operation, dryRun) => request(
-    `/types/${encodeIdentifier(identifier)}/lifecycle`,
+  const lifecycle = (resource, identifier, operation, dryRun) => request(
+    `/${resource}/${encodeIdentifier(identifier)}/lifecycle`,
     {
       method: "POST",
       body: JSON.stringify({ operation, dryRun })
@@ -104,8 +132,82 @@ function createContentManagementClient(config) {
       method: "PUT",
       body: JSON.stringify(input)
     }),
-    inspectLifecycle: (identifier, operation) => lifecycle(identifier, operation, true),
-    applyLifecycle: (identifier, operation) => lifecycle(identifier, operation, false)
+    inspectLifecycle: (identifier, operation) => lifecycle("types", identifier, operation, true),
+    applyLifecycle: (identifier, operation) => lifecycle("types", identifier, operation, false),
+    listEntries: (input) => request(entryListPath(input)),
+    getEntry: (identifier, locale) => {
+      const query = locale ? `?locale=${encodeURIComponent(locale.trim())}` : "";
+      return request(
+        `/entries/${encodeIdentifier(identifier)}${query}`
+      );
+    },
+    createEntry: (input) => request("/entries", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateEntry: (identifier, input) => request(
+      `/entries/${encodeIdentifier(identifier)}`,
+      {
+        method: "PUT",
+        body: JSON.stringify(input)
+      }
+    ),
+    inspectEntryLifecycle: (identifier, operation) => lifecycle("entries", identifier, operation, true),
+    applyEntryLifecycle: (identifier, operation) => lifecycle("entries", identifier, operation, false),
+    listMedia: (input) => request(mediaListPath(input)),
+    uploadImage: (input) => {
+      const fileName = input.fileName.trim();
+      if (!fileName) {
+        throw new ContentManagementError({
+          message: "A descriptive image file name is required.",
+          code: "CONTENT_MEDIA_FILE_NAME_REQUIRED",
+          status: 0
+        });
+      }
+      return request("/media/images", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/octet-stream",
+          "X-Bacano-File-Name": encodedHeader(fileName),
+          ...input.altText ? { "X-Bacano-Alt-Text": encodedHeader(input.altText) } : {}
+        },
+        body: uploadBody(input.file)
+      });
+    },
+    listGroups: () => request("/groups"),
+    getGroup: (identifier) => request(
+      `/groups/${encodeIdentifier(identifier)}`
+    ),
+    createGroup: (input) => request("/groups", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateGroup: (identifier, input) => request(
+      `/groups/${encodeIdentifier(identifier)}`,
+      {
+        method: "PUT",
+        body: JSON.stringify(input)
+      }
+    ),
+    inspectGroupLifecycle: (identifier, operation) => lifecycle("groups", identifier, operation, true),
+    applyGroupLifecycle: (identifier, operation) => lifecycle("groups", identifier, operation, false),
+    listOptionLists: () => request("/option-lists"),
+    getOptionList: (identifier) => request(
+      `/option-lists/${encodeIdentifier(identifier)}`
+    ),
+    createOptionList: (input) => request("/option-lists", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateOptionList: (identifier, input) => request(
+      `/option-lists/${encodeIdentifier(identifier)}`,
+      {
+        method: "PUT",
+        body: JSON.stringify(input)
+      }
+    ),
+    inspectOptionListLifecycle: (identifier, operation) => lifecycle("option-lists", identifier, operation, true),
+    applyOptionListLifecycle: (identifier, operation) => lifecycle("option-lists", identifier, operation, false)
   };
 }
 export {

package/package.json

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

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

@@ -13,7 +13,9 @@ autenticación, marketing o Content por fuera de `@bacano/sdk`.
 
 Antes de extraer el diseño, identificar:
 
-- Web informativa o tienda virtual.
+- Web informativa, tienda virtual o sitio híbrido. Si permite una compra
+  completa, aplicar también los contratos de tienda a su superficie
+  transaccional.
 - Enlace al archivo, página, sección o frame de Figma.
 - Rutas que se implementarán y sus frames desktop/mobile.
 - Repositorio y cascarón Bacano que se reutilizarán.
@@ -74,11 +76,13 @@ 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) y
-[references/content-workflow.md](references/content-workflow.md). Preparar una
-matriz ruta → frame → componente → fuente de datos → estado responsive y
-determinar si el trabajo comienza desde Figma, desde Bacano Content o desde
-ambas fuentes.
+Leer [references/bacano-mapping.md](references/bacano-mapping.md),
+[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
+Figma, desde Bacano Content o desde ambas fuentes.
 
 - Reutilizar el starter, tokens y componentes existentes.
 - Consumir Bacano y Content mediante `@bacano/sdk`.
@@ -96,9 +100,19 @@ nunca repartir datos de prueba dentro de la UI. Si Content ya existe, mapearlo
 sin sobrescribir estructuras o entradas. Si el usuario pide materializar el
 blueprint, leer la sección de automatización de
 [references/content-workflow.md](references/content-workflow.md) y el contrato
-`CONTENT_TYPE_MANAGEMENT.md` incluido en `@bacano/sdk`. Solo crear o modificar
-tipos y componentes mediante el acceso temporal oficial; las entradas y media
-permanecen en el backoffice.
+`CONTENT_TYPE_MANAGEMENT.md` incluido en `@bacano/sdk`. Crear o modificar tipos,
+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 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
+después idioma principal del website. No traducir ni renombrar contratos ya
+utilizados por el storefront.
 
 Antes de modificar código, indicar brevemente qué rutas y componentes se
 implementarán y qué decisiones de diseño son inferidas.
@@ -113,9 +127,15 @@ Trabajar por página o conjunto pequeño de secciones:
 4. Integración Bacano real.
 5. Comparación visual y correcciones.
 
+No dar una página por validada únicamente porque compila. Comparar estructura,
+contenido, responsive e interacciones del corte antes de continuar y registrar
+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/bacano-mapping.md

@@ -7,9 +7,9 @@ negocio.
 
 Antes de programar, registrar por ruta:
 
-| Ruta | Frame | Componente | Fuente | Responsive | Estado |
-| --- | --- | --- | --- | --- | --- |
-| `/` | Home desktop/mobile | `Hero` | Content | 2 frames | pendiente |
+| Ruta | Frame | Componente | Fuente | Content | Responsive | Preview | Estado |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `/` | Home desktop/mobile | `Hero` | Content | `hero_inicio` | 2 frames | activa | pendiente |
 
 Fuentes posibles: Content, catálogo estático, live state, public config,
 checkout, auth u otra operación documentada del SDK.

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

@@ -19,12 +19,30 @@ 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.
 
+## Modelar sin extremos
+
+No convertir una página extensa en un único tipo gigante ni crear un componente
+para cada bloque visual. Separar una sección cuando tenga ciclo editorial,
+responsable, reutilización o repetición propios. Crear un componente compartido
+solo cuando coincidan tanto la estructura como el significado y la abstracción
+reduzca duplicación real.
+
+- Usar grupos para organizar entradas relacionadas por dominio o página.
+- Usar repetibles para pasos, integrantes, preguntas, tarjetas y otras
+  colecciones homogéneas.
+- Mantener directamente en el tipo los campos de un bloque exclusivo y simple.
+- Crear primero listas y componentes realmente compartidos; después los tipos
+  consumidores.
+- No hacer depender la UI del shape crudo de Content: fixture y mapper real
+  deben converger en el mismo view model.
+
 ## 2. Elegir el punto de partida
 
 ### Figma primero
 
 1. Extraer el contenido público visible y sus assets autorizados.
-2. Proponer tipos, keys, campos y entradas en `content-blueprint.json`.
+2. Resolver el idioma y proponer tipos, keys, campos y entradas en
+   `content-blueprint.json` siguiendo `CONTENT_TYPE_MANAGEMENT.md`.
 3. Crear fixtures locales que implementen el view model de la página.
 4. Implementar y validar el diseño contra esos fixtures.
 5. Entregar el blueprint al equipo de Content para crearlo en Bacano.
@@ -66,22 +84,22 @@ Estructura recomendada:
       "route": "/",
       "sections": [
         {
-          "sectionKey": "home-hero",
+          "sectionKey": "hero-inicio",
           "figmaNodeId": "1:20",
           "component": "HomeHero",
           "ownership": "content",
-          "contentTypeKey": "home_hero",
-          "entryKey": "home-main-hero",
+          "contentTypeKey": "hero_inicio",
+          "entryKey": "hero-principal-inicio",
           "status": "missing",
           "fields": [
             {
-              "key": "title",
+              "key": "titulo",
               "type": "text",
               "required": true,
               "sampleValue": "Compra para cada etapa"
             }
           ],
-          "fixture": "fixtures/home-hero.json"
+          "fixture": "fixtures/hero-inicio.json"
         }
       ]
     }
@@ -92,7 +110,9 @@ Estructura recomendada:
 El blueprint es una propuesta y una evidencia de coordinación, no una orden de
 escritura. No incluir IDs internos innecesarios, secretos, datos personales ni
 respuestas crudas de GraphQL. Mantener keys estables y registrar cambios que
-rompan el contrato.
+rompan el contrato. Las propiedades técnicas del formato del blueprint
+permanecen en inglés; los valores que representan tipos, componentes, campos y
+entradas definidos por la empresa siguen el idioma resuelto para el proyecto.
 
 ## 4. Fixtures temporales
 
@@ -132,9 +152,12 @@ Entregar una tabla legible con:
 El equipo de Content puede crear o ajustar la estructura desde Bacano. Si el
 usuario autoriza que el agente materialice el blueprint, usar exclusivamente
 `@bacano/sdk/content-management` y el token temporal generado desde **Conectar
-agente**. Confirmar la empresa, inventariar primero, crear componentes antes de
-sus consumidores y trabajar inicialmente en borrador. La skill no crea entradas,
-importaciones ni cargas de media.
+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`. 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
 
@@ -159,11 +182,24 @@ escribir:
 
 1. Pedir al usuario que genere un acceso temporal de 15, 30 o 60 minutos.
 2. Guardarlo solo en el entorno local del proceso del agente.
-3. Ejecutar `getContext()`, `listTypes()` y `getReferences()`.
+3. Ejecutar `getContext()`, comprobar sus `scopes`, y después `listTypes()`,
+   `listGroups()`, `listOptionLists()` y `getReferences()`.
 4. Mostrar el plan y esperar aprobación cuando altere estructuras existentes.
-5. Crear primero componentes y luego tipos consumidores, siempre en borrador.
-6. Para archivar o eliminar, inspeccionar dependencias y confirmar nuevamente.
+5. Crear primero listas y componentes, luego tipos consumidores, y mantener las
+   estructuras nuevas en borrador hasta validarlas.
+6. Si se concedió `content_entries:manage`, inventariar entradas por tipo, key y
+   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; 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.
+9. Publicar o modificar una entrada publicada solo con
+   `content_entries:publish` y una aprobación humana explícita.
 
 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. Las entradas y media permanecen bajo gestión editorial en Bacano.
+directo. Sin `content_media:upload`, toda media permanece bajo gestión
+editorial en el backoffice.

package/skills/bacano-figma-web/references/extraction-contract.md

@@ -87,6 +87,9 @@ Estado de página: `pending`, `extracted`, `implemented` o `validated`.
 
 Cada página requiere `route`, `name`, `status` y al menos un frame desktop o
 mobile con `nodeId` o `url`. No guardar secretos ni respuestas MCP completas.
+Antes de implementar, comprobar que las rutas no apuntan accidentalmente al
+mismo frame o `nodeId`. Una reutilización intencional debe quedar registrada en
+`assumptions`.
 
 ## Estrategia de consultas
 

package/skills/bacano-figma-web/references/implementation-quality.md

@@ -0,0 +1,67 @@
+# Calidad de implementación desde Figma
+
+Aplicar estas reglas al construir la interfaz. Son criterios de resultado, no
+una obligación de usar una librería concreta.
+
+## Responsive e inferencias
+
+Si Figma no incluye un frame móvil, construir una adaptación mobile first y
+registrarla como inferencia. Conservar jerarquía, contenido, orden semántico y
+acciones principales; apilar columnas cuando corresponda y evitar overflow
+horizontal. Verificar al menos móvil, tablet y escritorio.
+
+No convertir automáticamente toda colección en carrusel. Usarlo únicamente
+cuando mejore la exploración y asegurar scroll táctil, teclado, controles
+accesibles, dimensiones estables y pausa durante la interacción. Respetar
+`prefers-reduced-motion` cuando exista autoplay o movimiento.
+
+## Componentes e interacción
+
+Inspeccionar dependencias y componentes del proyecto antes de añadir paquetes.
+No imponer HeroUI, Embla, Motion, CSS Modules u otra librería; reutilizar el
+sistema existente y pedir autorización antes de introducir una dependencia
+visual relevante.
+
+Todo control interactivo necesita estado de hover cuando aplique,
+`focus-visible`, teclado, contraste y área táctil suficiente. Usar
+`aria-current="page"` en la navegación activa y no comunicar estados solo con
+color. Las animaciones no deben cambiar el layout final, dejar contenido útil
+oculto sin JavaScript ni ejecutarse contra la preferencia de movimiento
+reducido.
+
+## Perfil de exportación estática
+
+Cuando el hosting y el proyecto estén definidos como export estático, comprobar
+la configuración efectiva del framework. En Next.js suele incluir
+`output: "export"`, `trailingSlash: true` y una estrategia de imágenes
+compatible con exportación estática.
+
+Materializar durante el build contenido, rutas, metadata, sitemap y JSON-LD.
+Las rutas dinámicas editoriales deben enumerar todas las entradas publicadas y
+fallar de forma explícita si el snapshot esperado está vacío o incompleto.
+
+No introducir Route Handlers, API Routes, Server Actions, middleware, ISR,
+`force-dynamic` ni secretos de servidor en un proyecto que debe producir solo
+archivos estáticos. Esta prohibición no aplica automáticamente a un storefront
+híbrido o SSR: primero clasificar su arquitectura.
+
+Mantener un único bootstrap de configuración pública y un cliente Bacano por
+worker o árbol. Reutilizar esa misma información para páginas, metadata,
+sitemap, JSON-LD y provider; no consultar cada ruta por separado si existe un
+snapshot oficial compartido.
+
+## Preview y rutas editoriales
+
+Mantener una allowlist finita de patrones editoriales. Los índices pueden ser
+explícitos y los slugs de detalle pueden derivarse de las entradas publicadas;
+no aceptar una ruta arbitraria solo porque coincide con una cadena. Preview
+reutiliza componentes y mappers de producción, permanece fuera del sitemap y
+no habilita funciones transaccionales o marketing.
+
+## Diagnóstico antes de cambiar código
+
+Un `ORIGIN_NOT_ALLOWED` o un `403` al resolver la configuración durante el
+build suele indicar que el origen utilizado no está autorizado para el website.
+Verificar dominio canónico, orígenes permitidos y ambiente antes de alterar el
+cliente SDK. Una advertencia aislada sobre ausencia de caché del build no prueba
+por sí sola que el storefront esté defectuoso.

package/skills/bacano-figma-web/references/visual-validation.md

@@ -2,6 +2,10 @@
 
 Validar por cortes para evitar corregir 70 secciones al final.
 
+Para cada corte, distinguir `implementado`, `validado`, `pendiente de revisión
+humana`, `no aplica` y `bloqueado`. Si el usuario conserva la validación visual,
+no convertir su ausencia en una aprobación automática.
+
 ## Evidencia mínima por página
 
 - URL/ruta implementada.