import { FetchRepositoryBase } from "../../../shared/index.js"; import { type LockReleaseOutcome, type TemplateLockInfo } from "../locks/lockOwnership.js"; import type { CreateTemplateParams, CreateTemplateResponse, ListCSSResponse, ListCustomSnippetsResponse, ListJSResponse, ListLayoutsResponse, ListSnippetsResponse, SaveTemplateRequest, SaveTemplateResponse, TemplateListOptions, TemplateListType, TemplateResponse, TemplateSummary, UnpublishTemplateRequest, UpdateTemplateParams } from "./TemplatesTypes.js"; /** Lectura de un template con o sin conservar el lock que la lectura crea. */ export type ReadTemplateOptions = { /** Conserva el lock de edición del token (por defecto se libera). */ keepLock?: boolean | undefined; }; /** Step of a lock release that failed. */ export type LockReleaseStep = "lock" | "profile" | "delete"; /** * A lock of the token user that could not be released. * * - `lock`: `GET /locks/:id` failed with something other than 404. * - `profile`: the user of the token could not be read. * - `delete`: `DELETE /locks/:id` failed. */ export type LockReleaseError = { /** Stable code next to `message`, as every diagnostic in `data` has. */ code: "LOCK_RELEASE_FAILED"; lockId: number; templateId: number; step: LockReleaseStep; /** HTTP status, when the failure has one. */ status?: number; message: string; }; /** Result of a release that failed, with the step that failed. */ export type LockReleaseFailure = LockReleaseError & { outcome: "failed"; }; export declare class TemplatesRepository extends FetchRepositoryBase { /** * Locks this repository could not release. A repository is created for * each tool call, so this lists the failures of that call: the tool reports * them in `lockReleaseErrors`. */ readonly lockReleaseErrors: LockReleaseError[]; /** Usuario del token, leído una vez por repositorio. */ private currentUserLookup; /** * Endpoints de listado por tipo, en el orden en que se concatenan. * * `category` es la que corresponde al endpoint que devolvió el item: es un dato del origen, no * una inferencia sobre la ruta. */ private static readonly LIST_ENDPOINTS; /** * Lista los templates de un solo tipo desde su endpoint dedicado. * * Los cinco endpoints devuelven un array plano con `{id, uuid, name, path, type, status, * deletable, group}`. Se tolera además la forma `{ : [...] }` por si alguna versión de la * plataforma la envuelve. */ listTemplatesByType(siteId: number, listType: TemplateListType, options?: TemplateListOptions): Promise; /** * Lista el endpoint genérico `GET /sites/{id}/templates`. * * Fuente **complementaria**, nunca única. En sitios recién creados devuelve cero aunque el sitio * tenga sus templates (verificado: el sitio 5031 de `un.modyo.cloud` devuelve 0 aquí y 32 por los * endpoints de tipo). Pero es la única que incluye los templates de error y de contenido * —`site/errors/*`, `site/base/show`, `site/search/show`—, que no tienen endpoint dedicado: los * cinco candidatos (`/errors`, `/home`, `/category`, `/entry` y sus plurales) responden 404. * * No se pagina: esta versión de la API ignora `page` y `per_page` y no devuelve `meta`, así que * una sola llamada trae todo lo que el endpoint conoce. */ private listGenericTemplates; /** * Fetches all templates, uniendo los seis endpoints por tipo con el listado genérico. * * Los endpoints por tipo cubren todos los templates del sitio: `views` trae lo que no es layout, * snippet, CSS ni JS (vistas de error, `site/base/show`, `site/search/show`), que antes solo * aparecía en el genérico (VM-080). El genérico queda como fuente complementaria: en sitios * recién creados devuelve cero (#231), y el registro del endpoint dedicado gana al deduplicar. * * El genérico es best-effort: si falla, se devuelve lo que dieron los endpoints de tipo en vez de * perder también eso. La pérdida queda en el log de depuración. * * @param siteId - The ID of the site * @returns Promise resolving to the union of both sources, deduplicated by id */ getAllTemplates(siteId: number, options?: TemplateListOptions): Promise; /** * Fetches all templates with full body content. * Used by the download tool to get full template content. * * The list endpoints return templates without body. This method * fetches the list first, then retrieves each template individually * to get the body content. Uses parallel batches for performance. * * Cada GET individual crea un lock de edicion a nombre del token; este * metodo lo libera despues de leer cada template (#207, #278). Un lock que * no se pudo liberar queda en `lockReleaseErrors`. * * @param siteId - The ID of the site * @returns Promise resolving to array of all templates including body */ getAllTemplatesWithBody(siteId: number): Promise; getSnippets(siteId: number): Promise; getCustomSnippets(siteId: number): Promise; getCSSTemplates(siteId: number): Promise; getJSTemplates(siteId: number): Promise; getLayouts(siteId: number): Promise; /** * Creates a template and returns the platform receipt * (`{id, uuid, template_path, template_name}`). Use `createTemplateAndRead` * to get the template as stored. */ createTemplate(siteId: number, data: CreateTemplateParams): Promise; /** Creates a template and returns it as read afterwards. */ createTemplateAndRead(siteId: number, data: CreateTemplateParams, options?: ReadTemplateOptions): Promise; /** * GET de un template. **Crea un lock de edición** a nombre del token cuando * puede editar (`templates_controller.rb#lock_info`); quien lo llame libera * con `releaseTemplateLock`, o usa `readTemplate`. */ getTemplate(siteId: number, templateId: number): Promise; /** * Reads a template and releases the edit lock the read created, unless * `keepLock` is set. Only a lock held by the token user is released. */ readTemplate(siteId: number, templateId: number, options?: ReadTemplateOptions): Promise; updateTemplate(siteId: number, templateId: number, data: UpdateTemplateParams): Promise; deleteTemplate(siteId: number, templateId: number): Promise; /** * Saves a template body. The platform answers with versions and lock info, * not the template: use `saveTemplateAndRead` to get the stored template. */ saveTemplate(siteId: number, templateId: number, data: SaveTemplateRequest): Promise; /** * Saves a template body and returns the template as read afterwards. The * edit lock that the save takes is released unless `keepLock` is set, even * when the reread fails. */ saveTemplateAndRead(siteId: number, templateId: number, data: SaveTemplateRequest, options?: ReadTemplateOptions): Promise; /** * Libera los locks propios de varias respuestas, una vez por id; nunca * falla. Lo que no se pudo liberar queda en `lockReleaseErrors`. */ private releaseLocksQuietly; /** * Releases the edit lock that reading a template left to the token user. * * Uses the `lock_info` of the read: no lock id, or `valid_user: false` * (another user holds the lock), means there is nothing of ours to * release. Otherwise the lock owner is compared with the user of the token * before `DELETE /locks/:id`: the platform deletes any user's lock without * checking (`locks_controller.rb#destroy`). * * Never throws: a release that fails returns `outcome: "failed"` with the * step that failed, and is added to `lockReleaseErrors`. */ releaseTemplateLock(template: { id: number; lock_info?: TemplateLockInfo | null | undefined; }): Promise; /** `GET /profile` o, ante un 404, `GET /admin_users/me`. */ private currentUserId; /** * Tras un `GET` fallido: `POST /locks` devuelve el lock propio del template * (nuevo o existente) y 422 si lo tiene otro usuario; el propio se borra. * Devuelve una nota para el error si no se pudo comprobar. */ private releaseOwnTemplateLockAfterFailedRead; /** * Un intento posterior que libera el lock, o confirma que ya no existe, * deja sin efecto los fallos anteriores de ese mismo lock. */ private clearLockReleaseErrors; /** * Libera un lock solo si es del usuario del token. Sin lock candidato no * hace nada. Nunca lanza: un fallo devuelve el paso que falló y queda en * `lockReleaseErrors`. */ private releaseOwnLockById; unpublishTemplate(siteId: number, templateId: number, data?: UnpublishTemplateRequest): Promise; /** * Find a template by name, optionally restricted to one category's endpoint. * * Con `listType` consulta solo el endpoint de ese tipo; sin él, los cinco. En ningún caso pasa * por `GET /sites/{id}/templates`, que devuelve cero en sitios nuevos (#231). * * Returns the first exact match or null if not found. */ findTemplateByName(siteId: number, name: string, listType?: TemplateListType, options?: TemplateListOptions): Promise; /** * Find a template by UUID. El UUID es estable entre publicaciones, a diferencia del id. */ findTemplateByUuid(siteId: number, uuid: string, options?: TemplateListOptions): Promise; /** * Find a template by numeric id without fetching it individually. * * `getTemplate` crea un lock de edición que bloquea el `/save` posterior, así que las escrituras * resuelven por listado. Antes esto iba contra el endpoint genérico y fallaba con * `Template not found with ID` sobre templates que la lectura sí devolvía (#231). */ findTemplateById(siteId: number, id: number, options?: TemplateListOptions): Promise; /** * Find a template by name and return full template data including body. * The edit lock that the read creates is released unless `keepLock` is set. * Returns null if not found. */ findTemplateByNameWithBody(siteId: number, name: string, listType?: TemplateListType, options?: ReadTemplateOptions & TemplateListOptions): Promise; } //# sourceMappingURL=TemplatesRepository.d.ts.map