@bacano/sdk 1.2.6 → 1.2.7

package/CONTENT_ICONS.md

@@ -0,0 +1,113 @@
+# Iconos Bacano en Content y sitios web
+
+La biblioteca v6 ofrece **605 iconos**: los 600 dibujos de Bacano y cinco marcas sociales adicionales. Content guarda un ID estable como
+`bacano:carrito` dentro de `contentJson`; nunca guarda SVG, HTML ni una URL
+editable. Los dibujos propios heredan el color del texto. Instagram, Facebook,
+WhatsApp, YouTube y TikTok usan imágenes procedentes de sus paquetes de marca,
+sin recoloración. Sus nuevos IDs son `bacano:instagram`, `bacano:facebook`,
+`bacano:whatsapp`, `bacano:youtube` y `bacano:tiktok`. Los cinco símbolos
+genéricos anteriores mantienen sus IDs y se pueden recolorear. Cada par
+comparte el nombre de la red; en el selector se distinguen por «Color editable»
+y «Marca original». Consulta `provenance` si construyes tu propio selector.
+
+## Elegir el ID desde un agente
+
+Con un permiso temporal de Content, consulta las referencias antes de crear un
+tipo o una entrada:
+
+```ts
+const references = await content.getReferences();
+const icon = references.icons.find((item) => item.id === "bacano:carrito");
+if (!icon) throw new Error("El icono no está disponible en Bacano");
+```
+
+`icons` trae `id`, `concept`, `label`, `category`, `keywords` y `provenance`.
+Dos iconos pueden tener el mismo nombre: usa el ID para distinguirlos y
+`provenance` para saber si permiten cambiar el color. No inventes IDs. Define
+un campo `{ key: "icono", label: "Icono",
+type: "icon", sortOrder: 1 }` en un tipo editorial y envía el ID como valor:
+
+```ts
+await content.createEntry({
+  contentType: "beneficio",
+  key: "entrega_segura",
+  name: "Entrega segura",
+  locale: "es-CO",
+  content: { icono: icon.id, titulo: "Entrega segura" },
+});
+```
+
+Los iconos son válidos en entradas, componentes, filas repetibles y bloques
+adicionales de producto. No son un tipo de ficha técnica. Los ID desconocidos,
+URLs, SVG y HTML se rechazan al guardar.
+
+## Mostrar el icono en una web
+
+```tsx
+import { BacanoIcon } from "@bacano/sdk/react/icon";
+
+<BacanoIcon
+  id={String(entry.contentJson.icono)}
+  apiUrl="https://api.tudominio.com"
+  size={28}
+  className="text-blue-600"
+  decorative
+/>
+```
+
+`BacanoIcon` valida el ID. Para dibujos propios usa `mask-image` con
+`currentColor`; para las cinco marcas usa `background-image` y conserva sus
+colores. Solo solicita el archivo de cada icono renderizado: no importa los
+605 assets al bundle.
+Si el icono comunica información por sí mismo, usa `decorative={false}` y
+proporciona `label`. Para una web sin React:
+
+```ts
+import { resolveBacanoIcon } from "@bacano/sdk/icons";
+
+const icon = resolveBacanoIcon(
+  entry.contentJson.icono,
+  "https://api.tudominio.com",
+);
+// icon?.url es una URL pública de asset solo para IDs conocidos.
+```
+
+Para consultar un ID sin configurar la URL de la API, usa
+`getBacanoIcon(id)`. Devuelve sus metadatos o `null`. Si `resolveBacanoIcon`
+recibe un ID desconocido o una URL base vacía, también devuelve `null`.
+Importa estas funciones desde `@bacano/sdk/icons` y el componente desde
+`@bacano/sdk/react/icon`: así una web que no usa iconos no incluye el catálogo
+en sus entradas generales del SDK.
+
+Para los dibujos propios en una web sin React:
+
+```css
+.bacano-icon {
+  display: inline-block;
+  width: 1.5em;
+  height: 1.5em;
+  background: currentColor;
+  mask: var(--bacano-icon-url) center / contain no-repeat;
+  -webkit-mask: var(--bacano-icon-url) center / contain no-repeat;
+}
+```
+
+El sitio coloca `--bacano-icon-url: url("<icon.url>")` en el elemento. Si
+`icon.provenance === "official-brand"`, usa `<img src={icon.url}>` o una imagen
+de fondo con `contain`, sin `mask` ni `currentColor`; dale un nombre accesible
+si el icono no es decorativo. Usa las marcas para enlazar a los perfiles o
+contenidos correspondientes y respeta sus normas de uso.
+También puedes usar `listBacanoIcons()` para construir una lista local de
+opciones; esta función entrega metadatos, no los archivos. Los assets se
+sirven por `/assets/icons/v6/<asset>` con permiso de origen cruzado. Mantén
+el `apiUrl` del SDK apuntando a la API pública de Bacano, no a Hasura.
+
+## Publicación y compatibilidad
+
+Primero despliega API/assets y la migración de `content_field_types`; después
+el SDK y el editor. Una web antigua verá el ID en `contentJson` aunque todavía
+no dibuje el icono. Los IDs publicados no se reutilizan ni se retiran. Los diez SVG de
+la aprobación visual inicial siguen en `apps/frontend/public/iconos-muestra`
+solo como revisión; la fuente servida por la API es
+`apps/api/src/assets/icons/v6`. La API conserva las rutas v1, v2, v3 y v4 para webs que
+todavía usan los catálogos anteriores.

package/CONTENT_TYPE_MANAGEMENT.md

@@ -73,8 +73,8 @@ 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.
+- `getReferences()` para consultar categorías, subcategorías, listas de opciones,
+  unidades de medida e iconos Bacano válidos.
 - `listTypes()` y `getType(idOrKey)`.
 - `createType(input)` y `updateType(idOrKey, input)`.
 - `inspectLifecycle(idOrKey, operation)`.
@@ -98,6 +98,12 @@ El cliente ofrece:
   `reorderProductBlocks(productId, input)` y
   `retireProductBlock(productId, blockId, expectedUpdatedAt)`.
 
+Para campos editoriales `type: "icon"`, consulta `getReferences().icons` y
+guarda uno de sus IDs (por ejemplo `bacano:carrito`) en el contenido. No envíes
+SVG ni URL. La validación también cubre componentes y repetibles; las fichas
+técnicas no admiten este tipo. [CONTENT_ICONS.md](CONTENT_ICONS.md) explica
+cómo renderizarlo en la web sin descargar los 605 archivos de icono.
+
 ## Bloques adicionales de un producto
 
 Al generar un acceso con `product_content:manage`, indica de 1 a 50 IDs de

package/README.md

@@ -38,6 +38,7 @@ import { createContentManagementClient } from "@bacano/sdk/content-management";
 ```
 
 Lee [`CONTENT_TYPE_MANAGEMENT.md`](./CONTENT_TYPE_MANAGEMENT.md) antes de usarlo.
+Para iconos editoriales, consulta [`CONTENT_ICONS.md`](./CONTENT_ICONS.md).
 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

package/STOREFRONT_PAYMENTS.md

@@ -194,6 +194,14 @@ Referencia oficial: [API Openpay Colombia](https://documents.openpay.co/api/inde
 El comprador usa los medios habilitados por Openpay dentro de su página
 alojada; el SDK no pide tarjeta, PSE ni efectivo de forma separada.
 
+Si el storefront muestra el logotipo de Openpay, hacerlo solo para la opción
+devuelta por `getPaymentOptions()` con `gatewayCode === "OPENPAY"`. Es la marca
+de la pasarela, no otro método seleccionable; puede preceder a los logotipos
+de redes en la misma tarjeta. Mostrar logos de tarjetas, PSE o pago en tienda
+solo cuando su disponibilidad esté confirmada para esa integración y ambiente:
+la lista efectiva de medios pertenece al checkout alojado. El logotipo debe
+tener un nombre accesible y no sustituye la descripción ni el estado del método.
+
 ### Diagnóstico rápido
 
 | Síntoma | Acción segura |

package/STOREFRONT_PERFORMANCE.md

@@ -135,6 +135,19 @@ The first visible product image may use eager loading/high priority. Images
 below the fold and recommendation blocks must remain lazy. Storefronts must not
 append storage transformation query parameters manually.
 
+For image carousels, inspect the mobile network trace rather than assuming
+`loading="lazy"` prevents every offscreen request. Some carousel layouts still
+cause all slides to download. Keep the active and nearby slides ready, load
+additional slides as the user navigates, and verify that moving directly to a
+distant thumbnail still displays its image. Recommendations should not download
+every card image before the section is viewed.
+
+Test the product page and its cart/gallery interactions in the mobile browsers
+the storefront supports. If older Safari versions are in scope, do not rely on
+unpolyfilled newer array methods such as `toSorted()`; a copied array followed
+by `sort()` is a compatible alternative. A minified browser error alone is not
+enough to identify the failing component: reproduce it and inspect the stack.
+
 ### Banners and full-width heroes
 
 Editorial `ContentMedia` images additionally expose:
@@ -261,6 +274,24 @@ If the storefront refreshes public configuration in the browser, it must keep
 the static bootstrap while the refresh is pending and only replace it when the
 payload actually changes. Configuration failure must not blank the storefront.
 
+## Sitemap and robots delivery
+
+Static exports often publish all non-HTML files with the same cache policy.
+Keep long-lived `immutable` caching for fingerprinted assets, **not** for stable
+discovery URLs such as `/sitemap.xml` and `/robots.txt`. Serve those files with
+a short, revalidating TTL and invalidate the CDN on publication so a rebuilt
+catalog can be discovered. This is a hosting rule, not an SDK request.
+
+After deployment, check the canonical public URL with a real `GET`: status
+`200`, suitable content type, valid XML, expected URL count and canonical
+hosts. Compare that count with the generated routes and catalog snapshot;
+confirm that `robots.txt` names the sitemap and does not block it. A sitemap
+that opens in a browser can still have a delivery or search-console problem.
+If Search Console reports that it could not fetch the file, compare its last
+attempt with a live URL inspection before changing the XML. Once a delivery
+issue is fixed, submit the sitemap again as described in
+[Google's sitemap troubleshooting guide](https://support.google.com/webmasters/answer/7451001).
+
 Mount third-party authentication only on routes that require it, such as
 checkout, sign-in and customer account pages. Public catalog and product pages
 must not download an authentication runtime merely because buyer accounts are
@@ -304,6 +335,10 @@ not verified instead of inferring it from source code.
 - [ ] `srcset` and `sizes` are present on catalog and product media.
 - [ ] Live refresh is batched, debounced and failure-safe.
 - [ ] Recommendations and below-fold media do not block the primary content.
+- [ ] Carousels do not fetch every offscreen image on mobile; supported Safari
+      versions can navigate the product gallery after using the cart.
+- [ ] Public sitemap and robots responses are current and are not cached as
+      immutable assets.
 - [ ] Mobile and desktop Lighthouse runs show no material layout shift.
 - [ ] A production trace confirms no duplicated catalog, shipping or website
       bootstrap calls during the first navigation.

package/content-management-types.d.ts

@@ -3,7 +3,7 @@ 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" | "forms:manage" | "forms:publish" | "product_content:manage";
-export type ContentManagementFieldType = "boolean" | "component" | "date" | "link" | "measure" | "media" | "number" | "reference" | "repeater" | "rich_text" | "rich_text_full" | "select" | "slug" | "text" | "textarea";
+export type ContentManagementFieldType = "icon" | "boolean" | "component" | "date" | "link" | "measure" | "media" | "number" | "reference" | "repeater" | "rich_text" | "rich_text_full" | "select" | "slug" | "text" | "textarea";
 export interface ContentManagementChildFieldInput {
     id?: string | null;
     key: string;
@@ -182,6 +182,14 @@ export interface ContentManagementImageUploadResult extends ContentManagementMed
     reused: boolean;
 }
 export interface ContentManagementReferences {
+    icons: Array<{
+        id: string;
+        concept: string;
+        label: string;
+        category: string;
+        keywords: string[];
+        provenance: "original-bacano" | "official-brand";
+    }>;
     categories: Array<{
         code: string;
         name: string;