sass-template-common 0.10.14 → 0.10.16

package/README.md

@@ -1,36 +1,36 @@
-# sass-template-common
-
-Librería web, maqueta de configuración y componentes para proyectos sass.
-
-## Publicar nueva versión
-
-Para que los cambios se reflejen al publicar:
-
-1. **Subir versión** (obligatorio; si no, npm rechaza o se usa la misma versión):
-   ```bash
-   pnpm version:patch   # 0.3.21 → 0.3.22
-   # o
-   pnpm version:minor   # 0.3.21 → 0.4.0
-   pnpm version:major   # 0.3.21 → 1.0.0
-   ```
-
-2. **Build limpio + publicar**:
-   ```bash
-   pnpm run clean && pnpm run build && pnpm publish
-   ```
-   O en un solo paso (patch):
-   ```bash
-   pnpm release:patch
-   ```
-
-3. **`prepublishOnly`**: Antes de cada `pnpm publish` se ejecuta `clean` + `build`, así siempre se publica un build nuevo.
-
-4. **En proyectos que consumen la lib**: Actualizar la dependencia y reinstalar:
-   ```bash
-   pnpm update sass-template-common
-   # o cambiar la versión en package.json y luego
-   pnpm install
-   ```
-   Si usan versión fija (`"0.3.21"`), hay que actualizarla a la nueva (p. ej. `"0.3.22"`).
-
-**Si no ves los cambios:** comprueba que subiste la versión (`version:patch` o similar), que hiciste `clean` + `build` antes de publicar, y que el proyecto consumidor tiene actualizada la dependencia (o `^0.3.21` y ha ejecutado `pnpm update`).
+# sass-template-common
+
+Librería web, maqueta de configuración y componentes para proyectos sass.
+
+## Publicar nueva versión
+
+Para que los cambios se reflejen al publicar:
+
+1. **Subir versión** (obligatorio; si no, npm rechaza o se usa la misma versión):
+   ```bash
+   pnpm version:patch   # 0.3.21 → 0.3.22
+   # o
+   pnpm version:minor   # 0.3.21 → 0.4.0
+   pnpm version:major   # 0.3.21 → 1.0.0
+   ```
+
+2. **Build limpio + publicar**:
+   ```bash
+   pnpm run clean && pnpm run build && pnpm publish
+   ```
+   O en un solo paso (patch):
+   ```bash
+   pnpm release:patch
+   ```
+
+3. **`prepublishOnly`**: Antes de cada `pnpm publish` se ejecuta `clean` + `build`, así siempre se publica un build nuevo.
+
+4. **En proyectos que consumen la lib**: Actualizar la dependencia y reinstalar:
+   ```bash
+   pnpm update sass-template-common
+   # o cambiar la versión en package.json y luego
+   pnpm install
+   ```
+   Si usan versión fija (`"0.3.21"`), hay que actualizarla a la nueva (p. ej. `"0.3.22"`).
+
+**Si no ves los cambios:** comprueba que subiste la versión (`version:patch` o similar), que hiciste `clean` + `build` antes de publicar, y que el proyecto consumidor tiene actualizada la dependencia (o `^0.3.21` y ha ejecutado `pnpm update`).

package/dist/sass-template-common.d.ts

@@ -244,29 +244,51 @@ export declare type BucketOriginConfig = {
     proxyUrl?: string;
     /** Prefijo raíz del cliente dentro del bucket (ej. `'debate'`). */
     clientName: string;
-    /** Sirve el menú (sidebar/menu/footer/freeZone/cintillo + equipos/sites) desde el bucket. */
+    /**
+     * Sirve el menú (sidebar/menu/footer/freeZone/cintillo + equipos/sites) desde
+     * el bucket. Con el toggle ON, SIN fallback a CMS: si el bucket agota los 4
+     * intentos, se sirve vacío + registro en el debugPanel (`reportBucketOriginExhausted`).
+     */
     menu?: boolean;
-    /** Sirve los banners (home/seccion/nota) desde el bucket. */
+    /**
+     * Sirve los banners (home/seccion/nota) desde el bucket. Con el toggle ON, SIN
+     * fallback a CMS: si el bucket agota los 4 intentos, se sirve vacío + registro
+     * en el debugPanel.
+     */
     banners?: boolean;
     /**
      * [transicional] Sirve la config de los slots dinámicos de home
      * (`bloques/modulos-dinamicos/modulos-dinamicos.json`) desde el bucket en
      * lugar del fan-out N contra `/config/blocks-saas`. Toggle de migración: al
      * pasar todos los sitios a `true`, la rama legacy CMS se elimina y el toggle
-     * queda no-op (luego se remueve). ⚠ Requiere el adapter
-     * `mapBucketModulesToSlots`, aún sin implementar por depender del shape real
-     * del JSON — ver `PLAN_DYNAMIC_SLOTS_BUCKET_ORIGIN.md` §2. NO prender hasta
-     * que el adapter exista (hoy lanza si se activa).
+     * queda no-op (luego se remueve). El JSON keyea plano `Home_N` (sin subíndices);
+     * cada entry se resuelve con `resolveSlotContent` (content-fetch al CMS igual
+     * que legacy). SIN fallback de CONFIG a CMS: con el toggle ON el bucket es el
+     * método único; si agota los 4 intentos, los slots se sirven vacíos y se
+     * registra en el debugPanel (`reportBucketOriginExhausted`) para notar la falla.
+     * El fan-out CMS solo corre con el toggle OFF (sitios sin migrar).
+     * Ver `PLAN_DYNAMIC_SLOTS_BUCKET_ORIGIN.md` §4.3/§7.
      */
     slots?: boolean;
     /**
      * [transicional] Sirve la config del destacado dinámico
      * (`bloques/destacado/destacado.json`) desde el bucket en lugar de
-     * `/config/blocks`. Drop-in 1→1: asume el mismo envelope `{ data: [...] }`
-     * que el endpoint CMS (verificar contra el archivo real antes de prender —
-     * `PLAN_DYNAMIC_SLOTS_BUCKET_ORIGIN.md` §2 Q4). Cae al CMS legacy si el
-     * bucket agota reintentos, igual que `menu`/`banners`. Al migrar todos los
-     * sitios la rama legacy se elimina y el toggle queda no-op.
+     * `/config/blocks`. Es drop-in de TRANSPORTE (mismo `.data.data` que el CMS).
+     * ⚠ CONTRATO (verificado contra un sitio CMS funcional, golfo): el LAYOUT del
+     * destacado va en `data[0].block`, que debe ser uno de los 5 nombres de layout
+     * (`Diario` | `Diario con imagen` | `Super` | `3 notas verticales` |
+     * `3 notas horizontales`) — es la key que consume `DynamicMainSlot` vía el prop
+     * `component`. Los campos `value`/`size`/`title`/`link` NO los usa el destacado
+     * (en el CMS vuelven como tokens sin rellenar) → se ignoran. (Nota: existe
+     * `getMainBlockData`, que lee `value` contra `GetByOptions`, pero es otra ruta
+     * que el render vivo de golfo no usa.)
+     * El CONTENIDO (las notas) SIEMPRE sale del CMS (zona `destacadas`, sección
+     * provista por la app) — permanente, no transicional: este toggle solo mueve el
+     * ORIGEN DE LA CONFIG (bucket vs CMS), nunca el contenido. SIN fallback de CONFIG
+     * a CMS: con el toggle ON el bucket es el método único; si agota los 4 intentos,
+     * el destacado se sirve vacío y se registra en el debugPanel (`reportBucketOriginExhausted`).
+     * El CMS solo sirve la config con el toggle OFF (sitios sin migrar).
+     * Ver `PLAN_DYNAMIC_SLOTS_BUCKET_ORIGIN.md` §4.4/§7.
      */
     destacado?: boolean;
     /**
@@ -553,9 +575,7 @@ export declare class CommonServices {
     getEntitySection: (params: Params) => Promise<AxiosResponse<{
         data: Array<NewListResponse>;
     }, any, {}>> | undefined;
-    getMainMenu: (params: Params) => Promise<AxiosResponse<{
-        data: Array<MenuResponse>;
-    }, any, {}> | {
+    getMainMenu: (params: Params) => Promise<{
         data: {
             data: Array<MenuResponse>;
         };
@@ -583,9 +603,7 @@ export declare class CommonServices {
     getVideosList: (params: Params) => Promise<AxiosResponse<{
         data: Array<VideoResponseData>;
     }, any, {}>> | undefined;
-    getBanners: (params: Params) => Promise<AxiosResponse<{
-        data: Array<BannerResponse>;
-    }, any, {}> | {
+    getBanners: (params: Params) => Promise<{
         data: {
             data: Array<BannerResponse>;
         };
@@ -1050,7 +1068,7 @@ export declare class DynamicBlockServices extends CommonServices {
     }>;
 }
 
-export declare const DynamicComponents: ({ slots, DYNAMIC_SLOT_SUBINDEXES, stylesConfig, AutorIcon, config, banners, showTagBySection, pathname, }: Props_21) => JSX.Element[];
+export declare const DynamicComponents: ({ slots, DYNAMIC_SLOT_SUBINDEXES, stylesConfig, AutorIcon, config, banners, showTagBySection, pathname, }: Props_21) => ReactNode[];
 
 export declare const DynamicMainSlot: ({ component, data, banners, rightOnlyBanner, isHome, }: Props_20) => JSX.Element;
 
@@ -1147,7 +1165,10 @@ export declare function fetchMaybeBatched(route: string, fetchFn: (size: number,
  * Cache in-memory + deduplicación de requests en vuelo (misma clave → misma promesa).
  * TTL corto pensado para SSR: evita 4–5 GETs repetidos de menú/banners por instancia.
  */
-export declare function fetchWithConfigCache<T>(cacheKey: string, fetchFn: () => Promise<T>, ttlMs?: number): Promise<T>;
+export declare function fetchWithConfigCache<T>(cacheKey: string, fetchFn: () => Promise<T>, options?: number | {
+    ttlMs?: number;
+    shouldCache?: (value: T) => boolean;
+}): Promise<T>;
 
 export declare const Font: ({ config }: {
     config: Config;
@@ -1954,6 +1975,12 @@ export declare type LibraryConfig = {
      * comportamiento no cambia (sigue yendo al CMS). Si un archivo no existe
      * en el bucket para un sitio/tipo dado, el request falla simple (sin
      * fallback automático al CMS) — igual que cualquier otro fetch fallido.
+     *
+     * [offline] Cuando `PUBLIC_IS_OFFLINE === 'true'`, todos los archivos de bucket
+     * se leen de la subcarpeta `offline/` del mismo directorio
+     * (`.../${subtype}/offline/${subtype}.json`) y, si fallan tras agotar
+     * reintentos, NO caen al CMS ni al archivo online: se devuelve vacío. Ver
+     * `resolveBucketOriginUrl`.
      */
     BUCKET_ORIGIN?: BucketOriginConfig;
 };
@@ -2025,9 +2052,11 @@ export declare class MainComponentServices {
     readonly contract: ImageSizesContract;
     constructor(config: Config, imgSizes: any, axiosApi: AxiosInstance, exclude?: string, customMainImagesSizes?: string, imageSizes?: ImageSizesContractInput);
     getNewsListZone(params: Params): Promise<AxiosResponse<NewListResponse, any, {}> | undefined>;
-    getOutstandingBlock(params: Params): Promise<AxiosResponse<{
-        data: Array<Outstanding>;
-    }, any, {}> | undefined>;
+    getOutstandingBlock(params: Params): Promise<{
+        data: {
+            data: Array<Outstanding>;
+        };
+    } | undefined>;
     getNewsListZoneWrapper(section: string, size: number, imagesizes?: string): Promise<AxiosResponse<NewListResponse, any, {}> | undefined>;
     getNewsDestacadoDiario(section: string): Promise<never[] | AxiosResponse<NewListResponse, any, {}>>;
     getNewsDestacadoDiarioImage(section: string): Promise<never[] | AxiosResponse<NewListResponse, any, {}>>;
@@ -3291,6 +3320,18 @@ export declare const REPORT_REASONS: {
     readonly bullying: "Bullying o acoso";
 };
 
+/**
+ * Registra en el **debugPanel** (`DebugStore`, gated por `DEBUG_ENABLED`) que un
+ * recurso de `BUCKET_ORIGIN` agotó los reintentos. En un sitio con el toggle
+ * prendido, el bucket es el MÉTODO ÚNICO: NO se cae al CMS (eso solo pasa con el
+ * toggle OFF, en sitios sin migrar). El recurso se sirve VACÍO y esta entrada
+ * deja constancia explícita del "servido vacío, sin fallback" para que la falla
+ * se NOTE en el panel en vez de quedar enmascarada. (El fallo de red crudo ya lo
+ * registra `resilientFetch`; esta entrada agrega la decisión de no-fallback.)
+ * Ver `PLAN_DYNAMIC_SLOTS_BUCKET_ORIGIN.md` §7.
+ */
+export declare function reportBucketOriginExhausted(kind: string, url: string): void;
+
 export declare function reportComment({ publication, username, id, type, baseUrl, captchaToken, apiToken, securityToken, COMMENTS_VARS, }: ReportCommentParams): Promise<{
     type: string;
     message: string;
@@ -3322,22 +3363,42 @@ export declare type ReportReasonKey = keyof typeof REPORT_REASONS;
 export declare type RequiredGroup = Exclude<keyof ImageSizesContract, 'squareLg'>;
 
 /**
- * Reintenta `fn` con backoff exponencial, acotando cada intento con `timeoutMs`
- * (un fetch a un bucket S3 colgado no debe bloquear el request indefinidamente).
+ * Defaults alineados con AWS SDK JS v3 (`standard` retry + NodeHttpHandler):
+ * - maxAttempts 3 → 1 intento + 2 reintentos (`retries = 2`)
+ * - backoff exponencial con full jitter (base 100ms, cap 20s)
+ * - timeout por intento (SSR): el SDK no lo pone por defecto; acá sí para no
+ *   colgar el render si el bucket no responde.
+ */
+export declare const RESILIENT_FETCH_DEFAULTS: {
+    readonly retries: 2;
+    readonly timeoutMs: 2500;
+    readonly baseDelayMs: 100;
+    readonly maxDelayMs: 20000;
+};
+
+/**
+ * Reintenta `fn` con backoff exponencial + jitter (paridad SDK `standard`),
+ * acotando cada intento con `timeoutMs` (un fetch a un bucket S3 colgado no
+ * debe bloquear el request indefinidamente).
  * Si se agotan los reintentos (o el error no es reintentable, ej. 404), registra el
  * fallo en DebugStore y devuelve `fallback` en vez de rechazar: una falla del bucket
  * no debe tumbar el render del sitio consumidor.
  */
-export declare function resilientFetch<T, F>(fn: () => Promise<T> | T, fallback: F, { label, endpoint, params, retries, timeoutMs, baseDelayMs, }: ResilientFetchOptions): Promise<T | F>;
+export declare function resilientFetch<T, F>(fn: () => Promise<T> | T, fallback: F, { label, endpoint, params, retries, timeoutMs, baseDelayMs, maxDelayMs, }: ResilientFetchOptions): Promise<T | F>;
 
 export declare interface ResilientFetchOptions {
     /** Identifica el fetch en logs y en el DebugStore (ej. '/news-list-zone', 'bucket:menu'). */
     label: string;
     endpoint?: string;
     params?: Record<string, any>;
+    /**
+     * Reintentos adicionales tras el primer intento.
+     * Default 2 → 3 intentos totales (paridad con `maxAttempts: 3` del SDK).
+     */
     retries?: number;
     timeoutMs?: number;
     baseDelayMs?: number;
+    maxDelayMs?: number;
 }
 
 /**
@@ -3349,7 +3410,18 @@ export declare function resolveBatchCount(): number;
 
 export declare function resolveBucketMenuSubtype(path?: string): string;
 
-export declare function resolveBucketOriginUrl(bucket: BucketOriginConfig, servicePrefix: string | undefined, type: 'menu' | 'banners' | 'bloques', subtype: string): string;
+/**
+ * Arma la URL del recurso en el bucket:
+ * `${base}/${clientName}/${site}/${type}/${subtype}/${subtype}.json`.
+ *
+ * En modo offline (`PUBLIC_IS_OFFLINE === 'true'`) el consumidor pasa
+ * `offline = true` y el archivo se resuelve dentro de la subcarpeta `offline/`
+ * del MISMO directorio: `.../${subtype}/offline/${subtype}.json`. La variante
+ * offline es un archivo aparte que convive con el de producción
+ * (`.../${subtype}/${subtype}.json`); el consumidor NO cae al CMS ni al archivo
+ * online si la offline falla (ver getMainMenu/getBanners/getDynamicSlots/destacado).
+ */
+export declare function resolveBucketOriginUrl(bucket: BucketOriginConfig, servicePrefix: string | undefined, type: 'menu' | 'banners' | 'bloques', subtype: string, offline?: boolean): string;
 
 /**
  * Recibe lo que el app mande hoy (contrato completo, parcial, o nada) y