@bacano/sdk 1.1.13 → 1.1.15

package/CONTENT_TYPE_MANAGEMENT.md

@@ -2,9 +2,9 @@
 
 `@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.
+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
@@ -30,8 +30,8 @@ Scopes disponibles:
 - `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.
+- `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.
@@ -77,6 +77,8 @@ El cliente ofrece:
   `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
 
@@ -317,8 +319,9 @@ Reglas obligatorias:
    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.
+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.
@@ -328,6 +331,45 @@ 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
@@ -385,12 +427,16 @@ omitas opciones existentes por accidente en una actualización.
 - 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 carga archivos ni crea media; puede relacionar media existente validada.
+- 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.

package/README.md

@@ -34,10 +34,11 @@ 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.
+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
 

package/content-management-types.d.ts

@@ -113,6 +113,35 @@ export interface ContentManagementEntryList {
     entries: ContentManagementEntry[];
     total: number;
 }
+export interface ContentManagementMedia {
+    id: string;
+    fileId: string;
+    name: string;
+    mediaKind: "image";
+    mimeType: string;
+    sizeBytes: number;
+    width: number | null;
+    height: number | null;
+    altText: string;
+    createdAt: string;
+}
+export interface ContentManagementMediaListInput {
+    search?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface ContentManagementMediaList {
+    items: ContentManagementMedia[];
+    total: number;
+}
+export interface ContentManagementImageUploadInput {
+    file: Blob | ArrayBuffer | Uint8Array;
+    fileName: string;
+    altText?: string;
+}
+export interface ContentManagementImageUploadResult extends ContentManagementMedia {
+    reused: boolean;
+}
 export interface ContentManagementReferences {
     categories: Array<{
         code: string;
@@ -245,6 +274,8 @@ export interface ContentManagementClient {
     updateEntry(identifier: string, input: ContentManagementEntryInput): Promise<ContentManagementEntry>;
     inspectEntryLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
     applyEntryLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
+    listMedia(input?: ContentManagementMediaListInput): Promise<ContentManagementMediaList>;
+    uploadImage(input: ContentManagementImageUploadInput): Promise<ContentManagementImageUploadResult>;
     listGroups(): Promise<ContentManagementGroup[]>;
     getGroup(identifier: string): Promise<ContentManagementGroup>;
     createGroup(input: ContentManagementGroupInput): Promise<ContentManagementGroup>;

package/content-management.cjs

@@ -68,6 +68,24 @@ function entryListPath(input = {}) {
   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;
@@ -98,7 +116,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
         }
       }
@@ -161,6 +179,26 @@ function createContentManagementClient(config) {
     ),
     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)}`

package/content-management.js

@@ -43,6 +43,24 @@ function entryListPath(input = {}) {
   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;
@@ -73,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
         }
       }
@@ -136,6 +154,26 @@ function createContentManagementClient(config) {
     ),
     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)}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacano/sdk",
-  "version": "1.1.13",
+  "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

@@ -77,7 +77,8 @@ 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),
-[references/content-workflow.md](references/content-workflow.md) y
+[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
@@ -103,7 +104,10 @@ blueprint, leer la sección de automatización de
 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 y publicar requiere permiso y aprobación explícitos.
+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
@@ -129,7 +133,9 @@ 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/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

@@ -155,7 +155,9 @@ usuario autoriza que el agente materialice el blueprint, usar exclusivamente
 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`; no carga media ni publica sin el scope específico.
+`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
 
@@ -189,7 +191,8 @@ escribir:
    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.
+   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.
@@ -198,5 +201,5 @@ escribir:
 
 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. La carga de media permanece bajo gestión editorial en Bacano hasta que
-exista el scope y endpoint administrativo oficial.
+directo. Sin `content_media:upload`, toda media permanece bajo gestión
+editorial en el backoffice.