@bacano/sdk 1.2.5 → 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
@@ -288,10 +289,12 @@ await client.init();
 
 ### 3. Browse Products (No Auth Required)
 
-`catalog.getProducts()` only returns products that are active, enabled for the
-website branch, have a valid `CLIENT` price and have available
-inventory in one of the inventory sources configured for the website. Websites
-without custom sources continue using the branch's default warehouse.
+`catalog.getProducts()` returns products that are active, published for the
+website, enabled for its branch and have a valid `CLIENT` price. By default it
+excludes sold-out products, but a website may show them globally or override
+that choice per published product. The SDK applies this rule; a visible
+sold-out product remains unavailable for purchase. Websites without custom
+inventory sources continue using the branch's default warehouse.
 
 ```typescript
 // List products
@@ -317,7 +320,7 @@ const affordable = await client.catalog.getProducts({
   maxPrice: 50,
 });
 
-// In-stock only. This is already the website default, kept for UI clarity.
+// Strictly in-stock, even if this website displays sold-out products.
 const available = await client.catalog.getProducts({ inStock: true });
 
 // Filter by color
@@ -353,7 +356,7 @@ const filtered = await client.catalog.getProducts({
 // Single product
 const product = await client.catalog.getProduct("product-uuid");
 
-// Static builds: fetch the complete sellable catalog and its first renderable
+// Static builds: fetch the complete visible catalog and its first renderable
 // catalog page. This is the canonical source for initial HTML, routes,
 // metadata, sitemap and product page data.
 const bootstrap = await client.catalog.getStaticCatalogBootstrap({
@@ -369,7 +372,8 @@ const productByRoute = new Map(
   bootstrap.products.map((item) => [item.slug || item.id, item]),
 );
 
-// Cards and filters use product.variants. Detail selectors use the official
+// Cards and filters use product.variants. These can include sold-out variants
+// if the website permits their display. Detail selectors use the official
 // helper so sold-out sizes remain visible and older snapshots stay compatible.
 const detailVariants = getProductDetailVariants(product!);
 

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

@@ -49,9 +49,11 @@ if this contract fails; they must not silently publish an empty catalog.
 
 The static bootstrap deliberately exposes two projections on each product:
 
-- `product.variants` contains only variants that were saleable when Bacano
-  generated the catalog page. Cards, price ranges, filters and listing
-  visibility must use this projection.
+- `product.variants` contains variants eligible for this website's listings.
+  It can include sold-out variants when the website setting or this product's
+  per-website exception allows them to remain visible. Cards, price ranges,
+  filters and listing visibility must use this projection; visibility is not
+  permission to purchase.
 - `product.detailVariants` also contains enabled, published variants with a
   public price that are currently sold out. Product detail selectors must use
   this projection so a customer can see unavailable sizes instead of assuming
@@ -71,8 +73,13 @@ const liveState = await client.catalog.getProductLiveState(
 `getProduct()` and `getProductBySlug()` expose the complete detail projection
 through `variants` as well. A sold-out variant returns `inStock: false` and
 `maxPurchasableQuantity: 0` from live state. Never use `detailVariants` to
-calculate a card's minimum price or to make a completely sold-out product
-appear in listings.
+calculate a card's minimum price or independently decide whether a completely
+sold-out product belongs in listings. The SDK applies the website rule and the
+product's per-website exception to listings, static routes, search suggestions
+and recommendations. `getProducts({ inStock: true })` remains strictly
+in-stock. The public SDK reads these rules; their administration belongs in
+Bacano. Changing them requires rebuilding static routes and catalog HTML;
+live-state refresh cannot add a route missing from the build.
 
 ## Live price and availability
 
@@ -128,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:
@@ -254,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
@@ -297,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;

package/graphql.cjs

@@ -122,6 +122,12 @@ var GET_PRODUCTS = (
       id
       name
       description
+      product_website_publications(
+        where: { website_id: { _eq: $websiteId }, is_visible: { _eq: true } }
+        limit: 1
+      ) {
+        show_when_out_of_stock
+      }
       long_description
       slug
       seo_title
@@ -357,6 +363,12 @@ var GET_PRODUCT_BY_PK = (
       limit: 1
     ) {
       id
+      product_website_publications(
+        where: { website_id: { _eq: $websiteId }, is_visible: { _eq: true } }
+        limit: 1
+      ) {
+        show_when_out_of_stock
+      }
       product_option_group_members(limit: 1) {
         group {
           id
@@ -606,6 +618,12 @@ var GET_PRODUCT_SEO_ENTRIES = (
       id
       name
       slug
+      product_website_publications(
+        where: { website_id: { _eq: $websiteId }, is_visible: { _eq: true } }
+        limit: 1
+      ) {
+        show_when_out_of_stock
+      }
       seo_title
       seo_description
       seo_image_file_id
@@ -2108,6 +2126,7 @@ var GET_PRODUCT_FILTERS = (
   query GetProductFilters(
     $companyId: uuid!
     $chainId: uuid!
+    $websiteId: uuid!
     $where: products_bool_exp = {}
     $attributeListKey: String!
   ) {
@@ -2115,6 +2134,12 @@ var GET_PRODUCT_FILTERS = (
       where: {
         _and: [
           { company_id: { _eq: $companyId } }
+          {
+            product_website_publications: {
+              website_id: { _eq: $websiteId }
+              is_visible: { _eq: true }
+            }
+          }
           {
             chain_products: {
               chain_id: { _eq: $chainId }
@@ -2127,6 +2152,12 @@ var GET_PRODUCT_FILTERS = (
       }
     ) {
       id
+      product_website_publications(
+        where: { website_id: { _eq: $websiteId }, is_visible: { _eq: true } }
+        limit: 1
+      ) {
+        show_when_out_of_stock
+      }
       category
       subcategory
       color
@@ -2234,6 +2265,7 @@ var GET_SEARCH_SUGGESTIONS = (
   query GetSearchSuggestions(
     $companyId: uuid!
     $chainId: uuid!
+    $websiteId: uuid!
     $term: String!
     $productLimit: Int = 5
     $brandLimit: Int = 3
@@ -2241,6 +2273,10 @@ var GET_SEARCH_SUGGESTIONS = (
     products(
       where: {
         company_id: { _eq: $companyId }
+        product_website_publications: {
+          website_id: { _eq: $websiteId }
+          is_visible: { _eq: true }
+        }
         chain_products: {
           chain_id: { _eq: $chainId }
           is_enabled: { _eq: true }
@@ -2253,6 +2289,29 @@ var GET_SEARCH_SUGGESTIONS = (
     ) {
       id
       name
+      product_website_publications(
+        where: { website_id: { _eq: $websiteId }, is_visible: { _eq: true } }
+        limit: 1
+      ) {
+        show_when_out_of_stock
+      }
+      product_variants(where: { is_disabled: { _eq: false } }) {
+        id
+        product_variant_prices(
+          where: {
+            price_type: { _eq: CLIENT }
+            _or: [
+              { chain_id: { _eq: $chainId } }
+              { chain_id: { _is_null: true } }
+            ]
+          }
+        ) {
+          id
+          price
+          price_type
+          chain_id
+        }
+      }
     }
     brands(
       where: {

package/graphql.js

@@ -62,6 +62,12 @@ var GET_PRODUCTS = (
       id
       name
       description
+      product_website_publications(
+        where: { website_id: { _eq: $websiteId }, is_visible: { _eq: true } }
+        limit: 1
+      ) {
+        show_when_out_of_stock
+      }
       long_description
       slug
       seo_title
@@ -297,6 +303,12 @@ var GET_PRODUCT_BY_PK = (
       limit: 1
     ) {
       id
+      product_website_publications(
+        where: { website_id: { _eq: $websiteId }, is_visible: { _eq: true } }
+        limit: 1
+      ) {
+        show_when_out_of_stock
+      }
       product_option_group_members(limit: 1) {
         group {
           id
@@ -546,6 +558,12 @@ var GET_PRODUCT_SEO_ENTRIES = (
       id
       name
       slug
+      product_website_publications(
+        where: { website_id: { _eq: $websiteId }, is_visible: { _eq: true } }
+        limit: 1
+      ) {
+        show_when_out_of_stock
+      }
       seo_title
       seo_description
       seo_image_file_id
@@ -2048,6 +2066,7 @@ var GET_PRODUCT_FILTERS = (
   query GetProductFilters(
     $companyId: uuid!
     $chainId: uuid!
+    $websiteId: uuid!
     $where: products_bool_exp = {}
     $attributeListKey: String!
   ) {
@@ -2055,6 +2074,12 @@ var GET_PRODUCT_FILTERS = (
       where: {
         _and: [
           { company_id: { _eq: $companyId } }
+          {
+            product_website_publications: {
+              website_id: { _eq: $websiteId }
+              is_visible: { _eq: true }
+            }
+          }
           {
             chain_products: {
               chain_id: { _eq: $chainId }
@@ -2067,6 +2092,12 @@ var GET_PRODUCT_FILTERS = (
       }
     ) {
       id
+      product_website_publications(
+        where: { website_id: { _eq: $websiteId }, is_visible: { _eq: true } }
+        limit: 1
+      ) {
+        show_when_out_of_stock
+      }
       category
       subcategory
       color
@@ -2174,6 +2205,7 @@ var GET_SEARCH_SUGGESTIONS = (
   query GetSearchSuggestions(
     $companyId: uuid!
     $chainId: uuid!
+    $websiteId: uuid!
     $term: String!
     $productLimit: Int = 5
     $brandLimit: Int = 3
@@ -2181,6 +2213,10 @@ var GET_SEARCH_SUGGESTIONS = (
     products(
       where: {
         company_id: { _eq: $companyId }
+        product_website_publications: {
+          website_id: { _eq: $websiteId }
+          is_visible: { _eq: true }
+        }
         chain_products: {
           chain_id: { _eq: $chainId }
           is_enabled: { _eq: true }
@@ -2193,6 +2229,29 @@ var GET_SEARCH_SUGGESTIONS = (
     ) {
       id
       name
+      product_website_publications(
+        where: { website_id: { _eq: $websiteId }, is_visible: { _eq: true } }
+        limit: 1
+      ) {
+        show_when_out_of_stock
+      }
+      product_variants(where: { is_disabled: { _eq: false } }) {
+        id
+        product_variant_prices(
+          where: {
+            price_type: { _eq: CLIENT }
+            _or: [
+              { chain_id: { _eq: $chainId } }
+              { chain_id: { _is_null: true } }
+            ]
+          }
+        ) {
+          id
+          price
+          price_type
+          chain_id
+        }
+      }
     }
     brands(
       where: {