@griddo/cx-render-mock 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,550 @@
+/**
+ * Núcleo PURO del test-double de render de CX — agnóstico de Cypress en VALOR y en TIPO.
+ *
+ * Contiene las decisiones difíciles del protocolo (clasificación por hash, diff por título, gate de
+ * build/start, shaping del body de build/end, colección de re-pending de la mitigación cross-job, y los knobs
+ * por defecto del render de un solo pase) SIN acoplarse a la cola de comandos de Cypress: cero `cy`/`Cypress`/`expect`/`window`,
+ * cero `import ... 'cypress'`, y ninguna firma devuelve `Cypress.Chainable` (solo tipos neutrales). Es el
+ * artefacto compartible: el shell Cypress de griddo-qa (`cypress/support/cx-render.ts`) y el motor de Promises
+ * del paquete (`./engine`) consumen ESTE módulo, de modo que el racional que causa los bugs vive en un único
+ * sitio (functional-core / imperative-shell). Ver `docs/cx-render-packaging-feasibility.md` §5/§6.
+ *
+ * Behavior-preserving: este código se EXTRAJO de `cx-render.ts` sin cambiar su comportamiento observable;
+ * las constantes, umbrales y predicados son idénticos a los del shell original.
+ */
+/**
+ * Modelo de live_status: data-driven en la BD pero ESTABLE por orden de seed (contrato code-grounded e2e-202 →
+ * griddo-api CONFIG/LiveStatusSeeder). El double no puede leer los flags de CONFIG en runtime → usa estos ids
+ * verificados.
+ */
+declare const LIVE_STATUS: {
+    readonly UNPUBLISHED: 1;
+    readonly PENDING_PUBLISHING: 2;
+    readonly LIVE: 3;
+    readonly PENDING_UNPUBLISHING: 4;
+};
+/** Los cuatro ids de live_status del contrato (1/2/3/4). */
+type LiveStatus = (typeof LIVE_STATUS)[keyof typeof LIVE_STATUS];
+/**
+ * Forma mínima de una página tal como la exponen los endpoints que consume el double: `GET page/{id}` (trae
+ * `hash` + `liveStatus`) y `site/{id}/pages?format=list` (trae `id` + `title` + `liveStatus`). Todos los
+ * campos son opcionales porque el body real de la API puede venir incompleto y el core no debe asumir.
+ */
+interface PageInfo {
+    id?: number;
+    title?: string;
+    hash?: string | null;
+    liveStatus?: {
+        id?: number;
+    } | null;
+}
+/** Cuerpo de `POST site/{id}/build/end` (lo que el CX real envía para resolver los transitorios). */
+interface BuildEndBody {
+    publishHashes: string[];
+    siteHash: string | null;
+    unpublishHashes: string[];
+    publishPagesIds: number[];
+}
+/** Esperas y topes del render. Todos sustituibles; los defaults están en `DEFAULT_TIMINGS`. */
+interface RenderTimings {
+    /**
+     * TECHO (ms) del settle ADAPTATIVO previo al ÚNICO build/start del render de un solo pase. El settle espera
+     * al spread ASÍNCRONO de las copias GLOBAL, pero ya NO es un sleep fijo: se sondea el listado del site hasta
+     * que dos sondas consecutivas devuelven la misma firma (`pageListSignature` → `decideSettleStep`), con este
+     * valor como tope. Racional: una constante fija no cubre una latencia variable — a 15s el pase único perdía
+     * rezagados bajo carga de CI (renderFlow2/002 agotaba los 3 intentos) y a 30-45s se paga tiempo muerto por
+     * site y por ronda en el 90% de renders que asientan en segundos. `<= 0` desactiva el settle por completo.
+     */
+    settleMs: number;
+    /** Intervalo (ms) entre sondas del settle adaptativo. */
+    settlePollMs: number;
+    /**
+     * Rondas máximas del orquestador auto-sanador `renderUntilLive`. NO baja a 1: con 1 quedaban sets ENTEROS
+     * not-Live en CI (el build/start del mock no captura TODAS las páginas en un pase; las rondas
+     * re-pend+re-render sí).
+     */
+    maxRounds: number;
+    /** Wait entre rondas del orquestador auto-sanador (ms). */
+    roundWaitMs: number;
+    /** Reintentos máximos de build/start mientras dé 4xx transitorio (~30s con el retry por defecto). */
+    buildStartMaxWaits: number;
+    /** Backoff entre reintentos de build/start en 4xx transitorio (ms). */
+    buildStartRetryWaitMs: number;
+}
+/** Defaults medidos de `RenderTimings`. El shell los sobreescribe por `Cypress.env`. */
+declare const DEFAULT_TIMINGS: RenderTimings;
+/** Paginación con la que se pide el listado de páginas de un site. Defaults en `DEFAULT_PAGE_LIST_QUERY`. */
+interface PageListQuery {
+    page: number;
+    itemsPerPage: number;
+}
+/** Defaults de `PageListQuery`. */
+declare const DEFAULT_PAGE_LIST_QUERY: PageListQuery;
+/**
+ * URL del listado del site (`site/{id}/pages?format=list`) que leen el diff por título y el re-pending.
+ * Centraliza la query string y la paginación — pura (string → string), sin acoplarse a Cypress (recibe
+ * `apiUrl` como argumento). ⚠️ Limitación HEREDADA: pide UNA sola página (300 ítems por defecto); un site con
+ * más páginas daría confirmación por título errónea. Se mitiga subiendo `itemsPerPage`, pero no pagina.
+ */
+declare const listPageUrl: (apiUrl: string, siteId: number, query?: PageListQuery) => string;
+/**
+ * Firma ESTABLE del estado render-relevante de un listado de páginas: `id:liveStatus:hash` por página, ordenado
+ * por id (el orden del listado puede variar entre sondas sin que el estado haya cambiado). Dos firmas iguales en
+ * sondas consecutivas = el backend ha dejado de mover estados/hashes (spread y recálculos asentados) → el
+ * build/start ya puede capturar el trabajo completo en un pase. Pura (datos → string), para el settle adaptativo.
+ */
+declare const pageListSignature: (items: PageInfo[]) => string;
+/** Decisión del settle adaptativo (unión discriminada: `wait` porta su `waitMs`). */
+type SettleDecision = {
+    action: "go";
+} | {
+    action: "wait";
+    waitMs: number;
+};
+/**
+ * Gate del settle ADAPTATIVO: decide si el backend ya está quiescente y el render puede arrancar.
+ *  - dos sondas consecutivas con la MISMA firma → `'go'` (quiescencia: nada se ha movido en un intervalo);
+ *  - `elapsedMs >= timings.settleMs` → `'go'` (techo: bajo carga patológica no se espera para siempre);
+ *  - resto → `'wait'` con `min(settlePollMs, settleMs - elapsedMs)` (el último wait no desborda el techo).
+ * La PRIMERA sonda (`prevSignature = null`) nunca decide `'go'` por firma: hacen falta dos muestras para saber
+ * que nada cambia. Con `settleMs <= 0` decide `'go'` inmediato (settle desactivado; el caller puede además
+ * ahorrarse la sonda).
+ */
+declare const decideSettleStep: (prevSignature: string | null, signature: string, elapsedMs: number, timings?: RenderTimings) => SettleDecision;
+/** Clasificación de una página según su `hash`/`status`, resultado de `classifyPage`. */
+type PageClassification = "publish" | "needsHash" | "skip";
+/**
+ * Clasifica una página por su HASH, como el CX real (griddo-cx store.ts:366-369): el TRABAJO = toda página
+ * con `hash != null`, SIN filtrar por estado. `build/end` publica el structured_data_content (has_been_published,
+ * que la API pública EXIGE vía includePendingPublishing:off) SOLO de los publishPagesIds/publishHashes que
+ * recibe; una copia GLOBAL/traducción puede alcanzar live(3) con su CONTENIDO aún sin publicar → si la
+ * SALTÁRAMOS por estar live(3) (como hacía el filtro `status===2` anterior), su contenido NUNCA se publicaría
+ * y la pública la excluiría (bug de traducciones en CI). Por eso:
+ *  - `hash != null` → `'publish'` (se publica su contenido aunque ya esté live(3); el render es un solo pase);
+ *  - `hash == null` y `status === PENDING_PUBLISHING` → `'needsHash'` (el spread aún no asignó el hash);
+ *  - resto (p.ej. live(3) con hash=null = ya publicada y con el hash nulado por endBuild) → `'skip'`.
+ */
+declare const classifyPage: (hash: string | null | undefined, status: number | undefined) => PageClassification;
+/**
+ * Diff SOFT por TÍTULO: dada la lista de páginas de los sites, devuelve los `wanted` que AÚN no están en
+ * `expectedStatus` (ausentes del listado o en otro estado). Se compara POR TÍTULO y no por id porque publicar/
+ * re-renderizar una GLOBAL canónica REASIGNA el id (memoria publish-canonical-global-page-reassigns-id) → un id
+ * de createSuite (o de un build/start previo) queda stale; el listado del site es la entidad renderizada real.
+ *
+ * Preferencia `statusByTitle`: prefiere `expectedStatus` si alguna entidad con ese título ya lo tiene (una
+ * global puede tener EDITOR + copia con distinto estado). El resultado (títulos que faltan) depende solo de si
+ * ALGUNA entidad con ese título alcanzó `expectedStatus`.
+ */
+declare const diffMissingByTitle: (items: PageInfo[], wanted: string[], expectedStatus: number) => string[];
+/** Shaping del cuerpo de `POST site/{id}/build/end` (normaliza `siteHash` ausente a `null`). */
+declare const buildEndBody: (publishHashes: string[], siteHash: string | null | undefined, unpublishHashes: string[], publishPagesIds: number[]) => BuildEndBody;
+/**
+ * Colección de re-pending de la MITIGACIÓN cross-job: de las páginas del listado, devuelve los ids in-site
+ * (deduplicados, en orden de aparición) de los títulos `missing` que NO están live. El barrido global
+ * INCONDICIONAL de endBuild (buildGlobalUnpublishAllWhere) puede despublicar globales QA de OTRO job → una
+ * página offline ya NO la recoge build/start, así que re-renderizar no la recupera; re-pendearla (upload-pending)
+ * la devuelve a pending(2) para que renderSiteToQuiescence la renderice. Acotado a copias in-site de `wanted`
+ * (el caller solo pasa los títulos deseados-live que faltan) y solo `st !== LIVE`.
+ */
+declare const collectRepublishIds: (items: PageInfo[], missing: string[]) => number[];
+/**
+ * Decisión del gate build/start-ready (unión discriminada: `retry` porta su `waitMs`, `proceed`/`fail` no).
+ */
+type BuildStartDecision = {
+    action: "proceed";
+} | {
+    action: "retry";
+    waitMs: number;
+} | {
+    action: "fail";
+};
+/**
+ * Gate build/start-ready: replica el timing del CX real (que dispara ~1 min después, cuando el pathing ya
+ * asentó, y nunca ve el 4xx transitorio) sin su latencia. El publish lanza el spread de las copias GLOBAL de
+ * forma ASÍNCRONA; hasta que termina, una copia puede existir con `pathId=null` y build/start (que corre
+ * fixAllPages → `pathId.split(...)`) devuelve 4xx TRANSITORIO. Por eso reintentamos SOLO mientras dé 4xx,
+ * cortando al 1er 200; si agota el presupuesto, el shell asserta RUIDOSO (no un CypressError crudo).
+ *  - `status < 400` → `'proceed'`;
+ *  - agotado el presupuesto (`startWaits >= timings.buildStartMaxWaits`) → `'fail'`;
+ *  - resto → `'retry'` con backoff `timings.buildStartRetryWaitMs`.
+ */
+declare const decideBuildStartStep: (status: number, startWaits: number, timings?: RenderTimings) => BuildStartDecision;
+/** Forma mínima de un site en `GET sites/all`: lo justo para saber si tiene render pendiente. */
+interface SiteBuildInfo {
+    id?: number;
+    /** La API lo marca cuando el site tiene cambios sin renderizar (señal QA-scoped: hash pendiente, no bloqueado). */
+    shouldBeUpdated?: boolean;
+}
+/**
+ * Ids de los sites con render PENDIENTE — lo que el CX real busca en cada pasada de su poll.
+ *
+ * `onlyIds` acota el resultado (el shell le pasa los sites del test en curso). Esa acotación NO es cosmética:
+ * el CX real es un único proceso global, pero el mock corre por test y a escala CI ~40 jobs comparten una BD;
+ * sin acotar, cada pasada arrastraría el trabajo de los demás (build/start → fixAllPages es pesado) y la BD se
+ * satura, tumbando incluso specs que no usan el mock.
+ */
+declare const selectPendingSites: (sites: SiteBuildInfo[], onlyIds?: number[]) => number[];
+
+/**
+ * Contrato de log mínimo, para que el paquete cuente qué está haciendo sin imponer una librería.
+ *
+ * Cuatro métodos y ninguna dependencia: encaja tal cual con `console`, y con pino, winston o el log del runner de
+ * tests envolviéndolo en cuatro líneas. Si no pasas ninguno, el paquete no escribe nada.
+ */
+interface Logger {
+    debug(message: string, meta?: unknown): void;
+    info(message: string, meta?: unknown): void;
+    warn(message: string, meta?: unknown): void;
+    error(message: string, meta?: unknown): void;
+}
+/** Logger que descarta todo. Es el que se usa cuando no inyectas uno. */
+declare const NOOP_LOGGER: Logger;
+/**
+ * Logger sobre `console`, por comodidad en scripts y ejemplos.
+ *
+ * @param level nivel mínimo que se emite. Por defecto `info`, así que los `debug` se descartan.
+ */
+declare const createConsoleLogger: (level?: "debug" | "info" | "warn" | "error") => Logger;
+
+/**
+ * Contrato del transporte HTTP y decoradores opcionales para envolverlo.
+ *
+ * El transporte es la única dependencia de runtime del paquete, y se inyecta: así no arrastra ningún cliente
+ * HTTP y funciona igual en Node, en un bundler o dentro de un runner de tests. Los decoradores son funciones que
+ * reciben un transporte y devuelven otro con el mismo contrato, de modo que reintentos, timeouts o trazas se
+ * añaden componiendo, sin que el motor sepa nada.
+ */
+
+/** Respuesta HTTP normalizada: status y body ya parseado. */
+interface TransportResponse {
+    status: number;
+    body: any;
+}
+/** Opciones de una request: cabeceras y body ya serializable. */
+interface RequestOptions {
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+/**
+ * Transporte HTTP inyectable. Impleméntalo sobre `fetch`, `axios`, `undici` o lo que uses.
+ *
+ * ⚠️ **No debe lanzar en 4xx/5xx**: devuelve `{ status, body }` y deja que el motor decida. Es deliberado: un
+ * 4xx de `build/start` es una respuesta esperada (la ruta del site aún no está lista), no un fallo. Un cliente
+ * que lance en error — como los que devuelven el body deserializado y tiran en no-2xx — necesita un adaptador
+ * que capture y traduzca a `{ status, body }`.
+ */
+interface Transport {
+    get(url: string, opts?: RequestOptions): Promise<TransportResponse>;
+    post(url: string, opts?: RequestOptions): Promise<TransportResponse>;
+    put(url: string, opts?: RequestOptions): Promise<TransportResponse>;
+}
+/** Métodos que un decorador puede tratar de forma distinta. */
+type TransportMethod = "get" | "post" | "put";
+/** Ajustes de {@link withRetry}. */
+interface RetryOptions {
+    /** Intentos totales, incluido el primero. Por defecto 3. */
+    attempts?: number;
+    /** Espera entre intentos (ms). Por defecto 500, y crece linealmente con el intento. */
+    delayMs?: number;
+    /**
+     * Métodos que se reintentan. Por defecto **solo `get`**.
+     *
+     * No es timidez: `build/start` toma un bloqueo del site y `build/end` lo libera, así que repetir a ciegas una
+     * escritura puede dejar el protocolo a medias. Amplíalo solo si sabes que tu caso lo tolera.
+     */
+    methods?: TransportMethod[];
+    /** Qué respuesta merece otro intento. Por defecto, los 5xx (un 4xx no se arregla repitiendo). */
+    shouldRetry?: (res: TransportResponse) => boolean;
+    /** Espera inyectable, para tests instantáneos. */
+    sleep?: (ms: number) => Promise<void>;
+    logger?: Logger;
+}
+/**
+ * Envuelve un transporte para que reintente los fallos pasajeros: una respuesta 5xx o un rechazo del cliente
+ * (red caída, DNS, socket cerrado). Agotados los intentos, deja pasar la última respuesta o relanza el error,
+ * para que quien llama decida.
+ *
+ * ```ts
+ * const transport = withRetry(myTransport, { attempts: 4 });
+ * ```
+ */
+declare const withRetry: (transport: Transport, opts?: RetryOptions) => Transport;
+/** Ajustes de {@link withTimeout}. */
+interface TimeoutOptions {
+    /** Milisegundos antes de dar la request por perdida. */
+    ms: number;
+    logger?: Logger;
+}
+/**
+ * Envuelve un transporte para que ninguna request se quede colgada para siempre: pasado el plazo, rechaza.
+ *
+ * ⚠️ **No cancela la request subyacente**, solo deja de esperarla: el paquete no conoce tu cliente HTTP, así que
+ * no puede abortarlo. Si necesitas cancelación real, implementa el plazo dentro de tu propio transporte con un
+ * `AbortController`.
+ */
+declare const withTimeout: (transport: Transport, opts: TimeoutOptions) => Transport;
+
+/**
+ * Error del paquete, con código.
+ *
+ * Un único tipo de error con un `code` en lugar de una jerarquía de clases: los consumidores necesitan
+ * distinguir *qué* falló para decidir (reintentar, avisar, abortar), y eso se hace igual de bien con un campo que
+ * con `instanceof`, sin obligar a importar siete clases.
+ */
+/** Códigos de {@link RenderError}. */
+declare const RENDER_ERROR_CODE: {
+    /** `build/start` siguió respondiendo error hasta agotar los reintentos: el site no llega a estar listo. */
+    readonly BUILD_START_NOT_READY: "BUILD_START_NOT_READY";
+    /** `build/end` respondió >= 400: el render no se ha aplicado y el bloqueo puede seguir puesto. */
+    readonly BUILD_END_FAILED: "BUILD_END_FAILED";
+    /** Se agotaron las rondas y algunos títulos no alcanzaron el estado final. Mira `missingTitles`. */
+    readonly TITLES_NOT_FINAL: "TITLES_NOT_FINAL";
+    /** No se pudo saber qué sites tenían render pendiente. */
+    readonly SITES_LOOKUP_FAILED: "SITES_LOOKUP_FAILED";
+    /** No se pudo leer el listado de páginas de un site. */
+    readonly PAGE_LIST_FAILED: "PAGE_LIST_FAILED";
+    /** Falló marcar páginas como pendientes de publicar. */
+    readonly MARK_PENDING_FAILED: "MARK_PENDING_FAILED";
+    /** Falló publicar un site. */
+    readonly PUBLISH_FAILED: "PUBLISH_FAILED";
+};
+/** Uno de los {@link RENDER_ERROR_CODE}. */
+type RenderErrorCode = (typeof RENDER_ERROR_CODE)[keyof typeof RENDER_ERROR_CODE];
+/** Datos opcionales que acompañan a un {@link RenderError}. */
+interface RenderErrorDetail {
+    /** Status HTTP de la respuesta que provocó el error, si lo hubo. */
+    status?: number;
+    /** Body de esa respuesta, tal cual, para poder diagnosticar sin volver a reproducir. */
+    body?: unknown;
+    /** Títulos que no alcanzaron su estado final. Solo en `TITLES_NOT_FINAL`. */
+    missingTitles?: string[];
+    /** Error original, si este envuelve a otro. Se expone también como `cause` nativa. */
+    cause?: unknown;
+}
+/**
+ * Error de este paquete. Siempre trae `code`; el resto del detalle depende de dónde falló.
+ *
+ * ```ts
+ * try {
+ * 	await engine.renderUntilLive([siteId], titles);
+ * } catch (error) {
+ * 	if (error instanceof RenderError && error.code === RENDER_ERROR_CODE.TITLES_NOT_FINAL) {
+ * 		console.warn("no llegaron:", error.missingTitles);
+ * 	}
+ * }
+ * ```
+ */
+declare class RenderError extends Error {
+    /** Qué falló, de forma comprobable sin leer el mensaje. */
+    readonly code: RenderErrorCode;
+    /** Status HTTP asociado, si el error viene de una respuesta. */
+    readonly status?: number;
+    /** Body de la respuesta asociada. */
+    readonly body?: unknown;
+    /** Títulos que no alcanzaron su estado final (`TITLES_NOT_FINAL`). */
+    readonly missingTitles?: string[];
+    constructor(code: RenderErrorCode, message: string, detail?: RenderErrorDetail);
+}
+
+/**
+ * Cliente interno sobre el transporte inyectado. **No es API pública**: no se exporta desde el índice del
+ * paquete.
+ *
+ * Concentra las tres cosas que antes repetían el motor y el publicador: montar las cabeceras, componer la URL
+ * a partir de `apiUrl`, y convertir una respuesta con error en un {@link RenderError} con su código. Así "qué
+ * cuenta como fallo" se decide en un único sitio.
+ */
+
+/** Lo que necesita cualquier pieza que hable con la API: el transporte, dónde está y con qué credencial. */
+interface ApiClientConfig {
+    transport: Transport;
+    apiUrl: string;
+    authToken: string;
+    /** Dónde contar lo que va pasando. Si no lo pasas, no se escribe nada. */
+    logger?: Logger;
+}
+
+/**
+ * Motor del protocolo de render: `build/start` → clasificar páginas por hash → `build/end`, con reintento por
+ * rondas hasta que los títulos pedidos alcanzan su estado final.
+ *
+ * Es una clase porque tiene estado (configuración, cliente HTTP) y dependencias que conviene invertir: el HTTP y
+ * el log. Las decisiones sin estado viven en `./core` como funciones puras; hablar con la API es cosa de
+ * `./api-client`.
+ */
+
+/** Dependencias del motor, inyectadas por constructor. */
+interface EngineDeps extends ApiClientConfig {
+    /** Espera de `ms` milisegundos. Por defecto, `setTimeout`; inyecta un no-op para que los tests no esperen. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Esperas y topes del render. Lo que no indiques se toma de {@link cxCore.DEFAULT_TIMINGS}. */
+    timings?: Partial<RenderTimings>;
+    /** Paginación del listado de páginas. Lo que no indiques se toma de {@link cxCore.DEFAULT_PAGE_LIST_QUERY}. */
+    pageList?: Partial<PageListQuery>;
+}
+/**
+ * Instánciala una vez con la configuración del entorno y reutilízala:
+ *
+ * ```ts
+ * const engine = new CxRenderEngine({ transport, apiUrl, authToken });
+ * await engine.renderUntilLive([siteId], ["Mi página"]);
+ * ```
+ */
+declare class CxRenderEngine {
+    private readonly api;
+    private readonly logger;
+    private readonly sleep;
+    private readonly timings;
+    private readonly pageList;
+    constructor(deps: EngineDeps);
+    /**
+     * Renderiza un site en **una sola pasada**: settle adaptativo → `build/start` → `GET page/{id}` →
+     * `build/end`.
+     *
+     * El settle previo da tiempo a que el backend termine de propagar las copias de las páginas globales; sin él,
+     * `build/start` devolvería una lista incompleta. Es ADAPTATIVO: sondea el listado hasta que dos sondas
+     * consecutivas coinciden (quiescencia) o hasta el techo `timings.settleMs` — rápido cuando el backend va
+     * suelto, paciente bajo carga. Las páginas que lleguen tarde no se reintentan aquí: de eso se encarga
+     * {@link renderUntilLive}.
+     *
+     * ⚠️ `build/start` deja el site bloqueado y `build/end` lo libera. En el camino normal `build/end` se emite
+     * siempre, pero si el transporte rechaza entre ambos el bloqueo queda colgado durante horas: llama a
+     * {@link releaseRenderLock} en tu `finally`.
+     *
+     * @throws {RenderError} `BUILD_START_NOT_READY` si el site no llega a estar listo, `BUILD_END_FAILED` si el
+     * render no se aplica.
+     */
+    renderSiteOnce(siteId: number): Promise<void>;
+    /**
+     * Settle ADAPTATIVO previo al build/start: sondea el listado del site cada `timings.settlePollMs` y arranca
+     * cuando dos sondas consecutivas devuelven la misma firma (`cxCore.pageListSignature`) o al agotar el techo
+     * `timings.settleMs` (la decisión es de `cxCore.decideSettleStep`). Best-effort: si el listado falla durante
+     * el settle, se procede al render en vez de morir aquí (peor caso = el de siempre, un pase incompleto que
+     * recogen las rondas de `renderUntilLive`). Con `settleMs <= 0` no sondea (settle desactivado).
+     */
+    private settleBeforeStart;
+    /**
+     * Renderiza **todos los sites que tengan render pendiente**, que es lo que hace el render real en cada pasada:
+     * pregunta al backend qué sites tienen cambios sin renderizar (`GET sites/all` → `shouldBeUpdated`) y los
+     * resuelve uno por uno.
+     *
+     * @param onlyIds acota a esos sites. **Úsalo si compartes la base de datos con otros procesos**: sin acotar,
+     * esta pasada arrastra también el trabajo pendiente de los demás, que es tan lento como caro.
+     * @returns los ids que ha renderizado.
+     * @throws {RenderError} `SITES_LOOKUP_FAILED` si no se puede consultar la lista de sites.
+     */
+    renderPendingSites(onlyIds?: number[]): Promise<number[]>;
+    /**
+     * Lleva los títulos pedidos a su estado final, reintentando lo que falte.
+     *
+     * Mientras queden títulos pendientes, vuelve a marcar como pendientes las copias que se hayan quedado
+     * despublicadas y renderiza otra vez, hasta `timings.maxRounds` rondas; la última confirma o lanza. Si todo
+     * está ya en su sitio, la primera comprobación pasa y no renderiza nada.
+     *
+     * @param expectedStatus estado final esperado. Por defecto `LIVE_STATUS.LIVE`; usa `LIVE_STATUS.UNPUBLISHED`
+     * para confirmar una despublicación.
+     * @throws {RenderError} `TITLES_NOT_FINAL` si tras la última ronda sigue faltando algún título.
+     */
+    renderUntilLive(siteIds: number[], titles: string[], expectedStatus?: number): Promise<void>;
+    /**
+     * Comprueba, sin renderizar, que los títulos están en `expectedStatus`.
+     *
+     * @throws {RenderError} `TITLES_NOT_FINAL`, con los títulos que faltan en `missingTitles`.
+     */
+    confirmPagesByTitle(siteIds: number[], titles: string[], expectedStatus?: number): Promise<void>;
+    /**
+     * Libera el bloqueo de render que deja `build/start`, emitiendo un `build/end` vacío.
+     *
+     * Llámalo en tu `finally` si un render puede abortar a medias. Es best-effort: no lanza aunque el backend
+     * responda con error, porque el caso normal es que ya no hubiera nada que liberar.
+     */
+    releaseRenderLock(siteId: number): Promise<void>;
+    /** Títulos que aún no están en `expectedStatus`, leyendo el listado completo de cada site. */
+    private missingPagesByTitle;
+    /** Devuelve a "pendiente de publicar" las copias despublicadas de los títulos que faltan. */
+    private republishMissingWantedLive;
+    /**
+     * Páginas de los sites indicados, **paginando hasta el final** del listado.
+     *
+     * Recorre páginas mientras el backend devuelva el lote completo: si llega uno más corto, es el último. Así un
+     * site con más páginas que `pageList.itemsPerPage` no se queda a medias, que era la causa de confirmaciones
+     * por título erróneas cuando solo se leía la primera página.
+     *
+     * @throws {RenderError} `PAGE_LIST_FAILED` si el backend no puede devolver el listado.
+     */
+    private listPages;
+}
+
+/**
+ * Publicación: marcar páginas como pendientes y publicar sites.
+ *
+ * Ojo con el reparto de responsabilidades: **esto no es parte del render**. En producción lo dispara la persona
+ * que pulsa "Publicar" en el CMS; el render solo reacciona a lo que ya está pendiente. Vive en este paquete como
+ * conveniencia para montar el escenario desde un script, no porque el render lo necesite.
+ *
+ * El orden importa: primero se marcan las páginas, luego se publica el site. Publicar es lo que hace que el
+ * backend las incluya en el siguiente `build/start`.
+ */
+
+/** Dependencias del publicador, inyectadas por constructor. Las mismas que el motor necesita para hablar con la API. */
+type PublisherDeps = ApiClientConfig;
+/**
+ * Dispara la publicación en el CMS. Complementa al motor de render: este deja el trabajo pendiente, el motor lo
+ * resuelve.
+ *
+ * ```ts
+ * const publisher = new CmsPublisher({ transport, apiUrl, authToken });
+ * await publisher.publishPages([siteId], [pageId]);
+ * await engine.renderUntilLive([siteId], ["Mi página"]);
+ * ```
+ */
+declare class CmsPublisher {
+    private readonly api;
+    private readonly logger;
+    constructor(deps: PublisherDeps);
+    /**
+     * Marca páginas como pendientes de publicar. Sin ids no hace nada.
+     *
+     * @throws {RenderError} `MARK_PENDING_FAILED` si el backend responde >= 400.
+     */
+    markPagesPending(pageIds: number[]): Promise<void>;
+    /**
+     * Publica los sites indicados, uno por uno.
+     *
+     * @throws {RenderError} `PUBLISH_FAILED` si el backend responde >= 400 para alguno.
+     */
+    publishSites(siteIds: number[]): Promise<void>;
+    /**
+     * Los dos pasos en orden: marca las páginas y publica los sites. Es el disparo completo que deja el trabajo
+     * listo para que el motor lo renderice.
+     */
+    publishPages(siteIds: number[], pageIds: number[]): Promise<void>;
+}
+
+/** Configuración de la fachada: la del motor, que es un superconjunto de la del publicador. */
+type CxRenderMockDeps = EngineDeps;
+/**
+ * Punto de entrada recomendado.
+ *
+ * ```ts
+ * const cx = new CxRenderMock({ transport, apiUrl, authToken, logger });
+ * await cx.publishAndRender([siteId], [pageId], ["Mi página"]);
+ * ```
+ */
+declare class CxRenderMock {
+    /** El motor de render, por si necesitas sus métodos sueltos. */
+    readonly engine: CxRenderEngine;
+    /** El disparo de publicación, por si quieres publicar sin renderizar. */
+    readonly publisher: CmsPublisher;
+    constructor(deps: CxRenderMockDeps);
+    /**
+     * El flujo entero: publica, renderiza y confirma que los títulos llegaron a su estado final. Libera el bloqueo
+     * de render de cada site si algo falla a medias.
+     *
+     * @param expectedStatus estado final esperado. Por defecto `LIVE_STATUS.LIVE`.
+     * @throws {RenderError} con el `code` de la etapa que falló.
+     */
+    publishAndRender(siteIds: number[], pageIds: number[], titles: string[], expectedStatus?: number): Promise<void>;
+}
+
+export { type BuildEndBody, type BuildStartDecision, CmsPublisher, CxRenderEngine, CxRenderMock, type CxRenderMockDeps, DEFAULT_PAGE_LIST_QUERY, DEFAULT_TIMINGS, type EngineDeps, LIVE_STATUS, type LiveStatus, type Logger, NOOP_LOGGER, type PageClassification, type PageInfo, type PageListQuery, type PublisherDeps, RENDER_ERROR_CODE, RenderError, type RenderErrorCode, type RenderErrorDetail, type RenderTimings, type RequestOptions, type RetryOptions, type SettleDecision, type SiteBuildInfo, type TimeoutOptions, type Transport, type TransportMethod, type TransportResponse, buildEndBody, classifyPage, collectRepublishIds, createConsoleLogger, decideBuildStartStep, decideSettleStep, diffMissingByTitle, listPageUrl, pageListSignature, selectPendingSites, withRetry, withTimeout };