@nubiia/mcp-freematica 0.6.3 → 0.7.0

package/README.md

@@ -1,6 +1,12 @@
 # mcp-freematica
 
-MCP server que expone operaciones del API REST de Freemática para ser consumidas por Claude a través de Nubiia.
+[![npm version](https://img.shields.io/npm/v/@nubiia/mcp-freematica)](https://www.npmjs.com/package/@nubiia/mcp-freematica)
+[![license: MIT](https://img.shields.io/npm/l/@nubiia/mcp-freematica)](./LICENSE)
+[![by Nubiia](https://img.shields.io/badge/by-Nubiia-6C4EE3)](https://nubiia.es)
+
+MCP server que expone operaciones del API REST de Freemática (ERP: facturación, cartera, proveedores, contabilidad, personal) para ser consumidas por asistentes de IA como Claude.
+
+> Built and maintained by **[Nubiia](https://nubiia.es)** — automatización e integraciones con IA para negocios (MCP, Holded, Pipedrive y más). ¿Quieres algo así para tu empresa? Escríbenos en **[nubiia.es](https://nubiia.es)**.
 
 ## Stack
 
@@ -53,6 +59,29 @@ MCP server que expone operaciones del API REST de Freemática para ser consumida
 | `freematica_list_albaranes_factura`                  | `GET /pven/v2/albaranes-facturas`                            | Lista paginada de vinculaciones albarán↔factura (idReg nativo + FIQL)                              |
 | `freematica_get_albaran_factura`                     | `GET /pven/v2/albaranes-facturas/{idReg}`                    | Detalle de una vinculación albarán-factura                                                         |
 | `freematica_list_resultados_facturacion`             | `GET /pvss/v1/facturacion-resultados`                        | Resultados del proceso batch de facturación automática de vigilancia (FIQL)                        |
+| `freematica_list_contratos`                          | `GET /pvss/v1/contratos`                                     | Lista paginada de cabeceras de contratos (solo filtros nativos: el API ignora FIQL aquí)           |
+| `freematica_get_contrato`                            | `GET /pvss/v1/contratos` (scan)                              | Busca un contrato por empresa + código natural (paginación interna + filtrado en cliente)          |
+| `freematica_list_servicios_contrato`                 | `GET /pvss/v1/contratos/{idReg}/servicios`                   | Servicios de un contrato                                                                           |
+| `freematica_get_servicio_contrato`                   | `GET /pvss/v2/contratos-servicios/{idReg}`                   | Detalle de un servicio de contrato                                                                 |
+| `freematica_list_contratos_opcionales`               | `GET /ppre/v2/contratos/opcionales`                          | Lista paginada de opcionales de contratos                                                          |
+| `freematica_get_contrato_opcionales`                 | `GET /ppre/v2/contratos/opcionales/{idReg}`                  | Detalle de un registro de opcionales                                                               |
+
+### Tools de escritura (requieren `FREEMATICA_ENABLE_WRITES=true`)
+
+Por defecto el servidor es de **solo lectura**. Con `FREEMATICA_ENABLE_WRITES=true` se registran además estas tools de creación y actualización. **No existe ninguna tool de borrado.** Todas las escrituras dejan log de auditoría (operación + endpoint + campos a nivel info; body completo a nivel debug).
+
+| Tool                                           | Endpoint Freemática                                             | Descripción                                                      |
+| ---------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `freematica_create_contrato`                   | `POST /pvss/v2/contratos`                                       | Alta de cabecera de contrato                                     |
+| `freematica_update_contrato`                   | `PUT /pvss/v2/contratos/{idReg}`                                | Actualización de cabecera de contrato                            |
+| `freematica_create_servicio_contrato`          | `POST /pvss/v2/contratos/{idReg}/servicios`                     | Alta de servicio (identificación derivada del idReg)             |
+| `freematica_update_servicio_fechas`            | `PUT /pvss/v2/contratos/{id}/servicio/{id}`                     | Fechas inicio/fin del servicio (mecanismo de baja)               |
+| `freematica_create_servicio_historico_precios` | `POST /pvss/v2/contratos/{id}/servicios-historico-precios/{id}` | Alta de revisión de precios del servicio                         |
+| `freematica_update_servicio_historico_precios` | `PUT /pvss/v2/contratos/{id}/servicios-historico-precios/{id}`  | Actualización de revisión de precios                             |
+| `freematica_create_servicio_facturacion_txt`   | `POST /pvss/v2/contratos/{id}/servicios-facturacion-txt/{id}`   | Alta de línea de texto de facturación                            |
+| `freematica_update_servicio_facturacion`       | `PUT /pvss/v2/contratos/{id}/servicios-facturacion/{id}`        | Datos de facturación del servicio (precios hora, forma de pago…) |
+| `freematica_create_contrato_opcionales`        | `POST /ppre/v2/contratos/opcionales`                            | Alta de opcionales de contrato                                   |
+| `freematica_update_contrato_opcionales`        | `PUT /ppre/v2/contratos/opcionales/{idReg}`                     | Actualización de opcionales de contrato                          |
 
 ## Filtros tipados (FIQL interno)
 
@@ -228,18 +257,19 @@ El servidor lee toda su configuración de **variables de entorno** al arrancar.
 
 Variables de entorno opcionales para tuning de comportamiento en producción:
 
-| Variable                                | Default                                              | Descripción                                                                                                                                     |
-| --------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `FREEMATICA_BASE_URL`                   | `https://api-p01.clientservicepanel.com/restsat/api` | Base URL del API de Freemática. Cambiar solo si Freemática cambia el host o se usa un entorno alternativo.                                      |
-| `FREEMATICA_TIMEOUT_MS`                 | `30000`                                              | Timeout por petición en milisegundos. Si el upstream no responde en este tiempo, el request se cancela con `network_error`.                     |
-| `FREEMATICA_MAX_RETRIES`                | `3`                                                  | Número máximo de reintentos para errores 5xx y errores de red. Los errores 4xx nunca se reintentan.                                             |
-| `FREEMATICA_CIRCUIT_BREAKER_THRESHOLD`  | `5`                                                  | Número de operaciones lógicas fallidas consecutivas (post-retry-exhaustion) necesarias para abrir el circuit breaker.                           |
-| `FREEMATICA_CIRCUIT_BREAKER_TIMEOUT_MS` | `30000`                                              | Tiempo en ms que el circuit breaker permanece abierto antes de pasar a half-open.                                                               |
-| `FREEMATICA_MAX_RESPONSE_SIZE_MB`       | `10`                                                 | Tamaño máximo de respuesta aceptada del upstream en MB. Respuestas mayores se truncan con aviso en el campo `truncated`.                        |
-| `MCP_TRANSPORT`                         | `stdio`                                              | Transporte: `stdio` (para Claude Desktop/Code) o `http` (para Nubiia). Equivale al flag `--transport=`.                                         |
-| `MCP_PORT`                              | `3000`                                               | Puerto TCP donde el servidor MCP expone `/mcp` y `/health`. Ignorado en modo stdio.                                                             |
-| `MCP_ALLOWED_ORIGINS`                   | `*`                                                  | CORS: lista de orígenes permitidos separados por coma, o `*` para todos. En producción restringir al dominio de Nubiia. Ignorado en modo stdio. |
-| `LOG_LEVEL`                             | `info`                                               | Nivel de log para pino: `fatal`, `error`, `warn`, `info`, `debug`, `trace`. En producción usar `info`. En desarrollo usar `debug`.              |
+| Variable                                | Default                                              | Descripción                                                                                                                                                |
+| --------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FREEMATICA_BASE_URL`                   | `https://api-p01.clientservicepanel.com/restsat/api` | Base URL del API de Freemática. Cambiar solo si Freemática cambia el host o se usa un entorno alternativo.                                                 |
+| `FREEMATICA_TIMEOUT_MS`                 | `30000`                                              | Timeout por petición en milisegundos. Si el upstream no responde en este tiempo, el request se cancela con `network_error`.                                |
+| `FREEMATICA_MAX_RETRIES`                | `3`                                                  | Número máximo de reintentos para errores 5xx y errores de red. Los errores 4xx nunca se reintentan.                                                        |
+| `FREEMATICA_CIRCUIT_BREAKER_THRESHOLD`  | `5`                                                  | Número de operaciones lógicas fallidas consecutivas (post-retry-exhaustion) necesarias para abrir el circuit breaker.                                      |
+| `FREEMATICA_CIRCUIT_BREAKER_TIMEOUT_MS` | `30000`                                              | Tiempo en ms que el circuit breaker permanece abierto antes de pasar a half-open.                                                                          |
+| `FREEMATICA_MAX_RESPONSE_SIZE_MB`       | `10`                                                 | Tamaño máximo de respuesta aceptada del upstream en MB. Respuestas mayores se truncan con aviso en el campo `truncated`.                                   |
+| `FREEMATICA_ENABLE_WRITES`              | `false`                                              | Registra las tools de escritura (`freematica_create_*` / `freematica_update_*`). Sin ella el servidor es de solo lectura. Valores: `true`/`false`/`1`/`0`. |
+| `MCP_TRANSPORT`                         | `stdio`                                              | Transporte: `stdio` (para Claude Desktop/Code) o `http` (para Nubiia). Equivale al flag `--transport=`.                                                    |
+| `MCP_PORT`                              | `3000`                                               | Puerto TCP donde el servidor MCP expone `/mcp` y `/health`. Ignorado en modo stdio.                                                                        |
+| `MCP_ALLOWED_ORIGINS`                   | `*`                                                  | CORS: lista de orígenes permitidos separados por coma, o `*` para todos. En producción restringir al dominio de Nubiia. Ignorado en modo stdio.            |
+| `LOG_LEVEL`                             | `info`                                               | Nivel de log para pino: `fatal`, `error`, `warn`, `info`, `debug`, `trace`. En producción usar `info`. En desarrollo usar `debug`.                         |
 
 ### De dónde salen las credenciales `x-auth-*`
 
@@ -510,6 +540,26 @@ node dist/index.js
 - API: `apidocs/Freematica API - Complete Collection.postman_collection.json`
 - CHANGELOG: `CHANGELOG.md`
 
+## About Nubiia
+
+This MCP server is built and maintained by **[Nubiia](https://nubiia.es)**.
+
+[Nubiia](https://nubiia.es) ayuda a empresas a **automatizar procesos e integrar sus herramientas con IA**: servidores MCP a medida, integraciones con ERPs y CRMs (Freemática, Holded, Pipedrive…), y agentes que conectan tus datos de negocio con asistentes como Claude. Este `@nubiia/mcp-freematica` es un ejemplo open source de lo que hacemos.
+
+👉 ¿Quieres una integración o automatización con IA para tu negocio? **[nubiia.es](https://nubiia.es)** · ✉️ [hola@nubiia.es](mailto:hola@nubiia.es)
+
+## Author
+
+Built by **[Nubiia](https://nubiia.es)** — [nubiia.es](https://nubiia.es) · [hola@nubiia.es](mailto:hola@nubiia.es)
+
+Maintainer: Samuel Fraga — [GitHub](https://github.com/iamsamuelfraga)
+
+## Links
+
+- [Nubiia — AI automation & integrations](https://nubiia.es)
+- [npm: @nubiia/mcp-freematica](https://www.npmjs.com/package/@nubiia/mcp-freematica)
+- [GitHub: nubiia-dev/mcp-freematica](https://github.com/nubiia-dev/mcp-freematica)
+
 ## Licencia
 
 MIT — ver `LICENSE`.

package/dist/clients/freematica-client.d.ts

@@ -7,7 +7,7 @@ import type { Cliente } from '../types/clientes.js';
 import type { ContactoCliente } from '../types/contactos-clientes.js';
 import type { MasterDataItem } from '../types/master-data.js';
 import type { OportunidadNegocio } from '../types/oportunidades-negocio.js';
-import type { VoContratosServMatAsignado } from '../types/contratos.js';
+import type { VoContrato, VoContratoServicio, VoContratosOpcionales, VoContratosServMatAsignado, VoServiciosFac, VoServiciosFacTxt, VoServiciosHistPr } from '../types/contratos.js';
 export interface ListResult<T> {
     items: T[];
     total: number;
@@ -601,6 +601,195 @@ export declare class FreematicaClient extends BaseClient {
         traspasado?: string;
         order?: string;
     }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista paginada de cabeceras de contratos.
+     *
+     * Endpoint: GET /pvss/v1/contratos
+     *
+     * IMPORTANTE: este endpoint IGNORA silenciosamente el query param `rQuery`
+     * (verificado empíricamente contra el API real el 2026-07-02: con un filtro
+     * FIQL válido devuelve el dataset completo sin error). Por eso solo se
+     * exponen los filtros nativos `codEmpresa` y `codDelegacion`; cualquier otro
+     * filtrado debe hacerse en cliente (ver `getContrato`).
+     *
+     * @param opts - Paginación + filtros nativos empresa/delegación + order.
+     * @returns Lista paginada de cabeceras de contrato (campos CTRT_*).
+     */
+    listContratos(opts?: ListOptions & {
+        empresa?: string;
+        delegacion?: string;
+        order?: string;
+    }): Promise<ListResult<VoContrato>>;
+    /**
+     * Busca una cabecera de contrato por sus códigos naturales.
+     *
+     * No existe un endpoint GET singular para contratos pvss y el listado ignora
+     * `rQuery`, así que se pagina el listado (items=200, máximo permitido por el
+     * API) filtrando en cliente por CTRT_COD hasta encontrar la coincidencia.
+     *
+     * @param opts - Códigos naturales del contrato.
+     * @returns Cabecera del contrato.
+     * @throws FreematicaError('not_found') si no existe.
+     */
+    getContrato(opts: {
+        empresa: string;
+        delegacion?: string;
+        codContrato: string;
+    }): Promise<VoContrato>;
+    /**
+     * Lista paginada de servicios de un contrato.
+     *
+     * Endpoint: GET /pvss/v1/contratos/{idContrato}/servicios
+     *
+     * @param idContrato - idReg opaco del contrato (Base64 "EMP__DELEG__COD").
+     * @param opts - Paginación + order.
+     * @returns Lista paginada de servicios (campos CTRTS_*).
+     */
+    listServiciosContrato(idContrato: string, opts?: ListOptions & {
+        order?: string;
+    }): Promise<ListResult<VoContratoServicio>>;
+    /**
+     * Detalle de un servicio de contrato por `idReg` opaco.
+     *
+     * Endpoint: GET /pvss/v2/contratos-servicios/{idreg}
+     *
+     * @param idReg - idReg opaco del servicio (Base64 "EMP__DELEG__CTRT__COD").
+     * @returns Servicio completo.
+     */
+    getServicioContrato(idReg: string): Promise<VoContratoServicio>;
+    /**
+     * Lista paginada de opcionales de contratos.
+     *
+     * Endpoint: GET /ppre/v2/contratos/opcionales
+     *
+     * @param opts - Paginación + order.
+     * @returns Lista paginada de opcionales (campos CON2_*).
+     */
+    listContratosOpcionales(opts?: ListOptions & {
+        order?: string;
+    }): Promise<ListResult<VoContratosOpcionales>>;
+    /**
+     * Detalle de un registro de opcionales de contrato por `idReg` opaco.
+     *
+     * Endpoint: GET /ppre/v2/contratos/opcionales/{idReg}
+     */
+    getContratoOpcionales(idReg: string): Promise<VoContratosOpcionales>;
+    /**
+     * Alta de cabecera de contrato.
+     *
+     * Endpoint: POST /pvss/v2/contratos — body VoContratos.
+     * Campos requeridos por el API: CTRT_DELEG, CTRT_DES, CTRT_FECHA, CTRT_COD_CLI.
+     *
+     * @param body - Campos CTRT_* del contrato.
+     * @returns El contrato creado (VoContratos).
+     */
+    createContrato(body: VoContrato): Promise<VoContrato>;
+    /**
+     * Actualización de cabecera de contrato.
+     *
+     * Endpoint: PUT /pvss/v2/contratos/{idReg} — body VoContratos.
+     *
+     * @param idReg - idReg opaco del contrato.
+     * @param body - Campos CTRT_* a actualizar.
+     * @returns Respuesta del API.
+     */
+    updateContrato(idReg: string, body: VoContrato): Promise<VoContrato>;
+    /**
+     * Alta de un servicio en un contrato.
+     *
+     * Endpoint: POST /pvss/v2/contratos/{idReg}/servicios — body VoServicios.
+     * Campos requeridos por el API: CTRTS_EMP, CTRTS_DELEG, CTRTS_CTRT (los
+     * mismos valores codificados en el idReg del contrato).
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param body - Campos CTRTS_* del servicio.
+     * @returns El servicio creado (VoServicios).
+     */
+    createServicioContrato(idContrato: string, body: VoContratoServicio): Promise<VoContratoServicio>;
+    /**
+     * Actualiza fechas de inicio y fin de un servicio.
+     *
+     * Endpoint: PUT /pvss/v2/contratos/{idContrato}/servicio/{idServicio}.
+     * Según el spec, este endpoint solo actualiza fecha inicio y fecha fin.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos CTRTS_* (fechas) a actualizar.
+     * @returns Respuesta del API.
+     */
+    updateServicioFechas(idContrato: string, idServicio: string, body: VoContratoServicio): Promise<VoContratoServicio>;
+    /**
+     * Actualiza los datos de facturación de un servicio.
+     *
+     * Endpoint: PUT /pvss/v2/contratos/{idContrato}/servicios-facturacion/{idServicio}.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos CTRTF_* a actualizar.
+     * @returns Respuesta del API.
+     */
+    updateServicioFacturacion(idContrato: string, idServicio: string, body: VoServiciosFac): Promise<VoServiciosFac>;
+    /**
+     * Alta de un texto de facturación de un servicio.
+     *
+     * Endpoint: POST /pvss/v2/contratos/{idContrato}/servicios-facturacion-txt/{idServicio}.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos CTRTFL_* del texto.
+     * @returns Respuesta del API.
+     */
+    createServicioFacturacionTxt(idContrato: string, idServicio: string, body: VoServiciosFacTxt): Promise<VoServiciosFacTxt>;
+    /**
+     * Alta de un registro de histórico de precios de un servicio.
+     *
+     * Endpoint: POST /pvss/v2/contratos/{idContrato}/servicios-historico-precios/{idServicio}.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos SERVHPR_* del histórico.
+     * @returns Respuesta del API (VoServiciosHistPr).
+     */
+    createServicioHistoricoPrecios(idContrato: string, idServicio: string, body: VoServiciosHistPr): Promise<VoServiciosHistPr>;
+    /**
+     * Actualiza un registro de histórico de precios de un servicio.
+     *
+     * Endpoint: PUT /pvss/v2/contratos/{idContrato}/servicios-historico-precios/{idServicio}.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos SERVHPR_* a actualizar.
+     * @returns Respuesta del API.
+     */
+    updateServicioHistoricoPrecios(idContrato: string, idServicio: string, body: VoServiciosHistPr): Promise<VoServiciosHistPr>;
+    /**
+     * Alta de un registro de opcionales de contrato.
+     *
+     * Endpoint: POST /ppre/v2/contratos/opcionales — body VoContratosOpcionales.
+     * Campos requeridos por el API: CON2_CODEMP, CON2_DELEG, CON2_TIPOCONT,
+     * CON2_NUMCONT, CON2_FCHCONT.
+     *
+     * @param body - Campos CON2_* del registro.
+     * @returns El registro creado.
+     */
+    createContratoOpcionales(body: VoContratosOpcionales): Promise<VoContratosOpcionales>;
+    /**
+     * Actualiza un registro de opcionales de contrato.
+     *
+     * Endpoint: PUT /ppre/v2/contratos/opcionales/{idReg}.
+     *
+     * @param idReg - idReg opaco del registro de opcionales.
+     * @param body - Campos CON2_* a actualizar.
+     * @returns Respuesta del API.
+     */
+    updateContratoOpcionales(idReg: string, body: VoContratosOpcionales): Promise<VoContratosOpcionales>;
+    /**
+     * Log de auditoría de operaciones de escritura.
+     *
+     * Nivel info: operación + endpoint + claves del body (sin valores).
+     * Nivel debug: body completo, para poder reconstruir la operación.
+     */
+    private logWrite;
     private listResource;
     /**
      * Helper genérico para endpoints de lista que soportan paginación + filtros FIQL

package/dist/clients/freematica-client.js

@@ -1,4 +1,4 @@
-import { BaseClient } from './base-client.js';
+import { BaseClient, FreematicaError } from './base-client.js';
 import { buildFiql, appendRquery } from './fiql-builder.js';
 import { CATALOG_ENDPOINTS } from '../schemas/master-data.js';
 import { ESTADO_CARTERA_FIQL_MAP, } from '../schemas/cartera.js';
@@ -1239,6 +1239,286 @@ export class FreematicaClient extends BaseClient {
         return { items: data.items, total: Number(data.total) };
     }
     // ---------------------------------------------------------------------------
+    // Contratos y Servicios (v0.7.0) — lectura
+    // ---------------------------------------------------------------------------
+    /**
+     * Lista paginada de cabeceras de contratos.
+     *
+     * Endpoint: GET /pvss/v1/contratos
+     *
+     * IMPORTANTE: este endpoint IGNORA silenciosamente el query param `rQuery`
+     * (verificado empíricamente contra el API real el 2026-07-02: con un filtro
+     * FIQL válido devuelve el dataset completo sin error). Por eso solo se
+     * exponen los filtros nativos `codEmpresa` y `codDelegacion`; cualquier otro
+     * filtrado debe hacerse en cliente (ver `getContrato`).
+     *
+     * @param opts - Paginación + filtros nativos empresa/delegación + order.
+     * @returns Lista paginada de cabeceras de contrato (campos CTRT_*).
+     */
+    async listContratos(opts = {}) {
+        const url = new URL('https://placeholder/pvss/v1/contratos');
+        if (opts.items !== undefined)
+            url.searchParams.set('items', String(opts.items));
+        if (opts.page !== undefined)
+            url.searchParams.set('page', String(opts.page));
+        if (opts.empresa !== undefined)
+            url.searchParams.set('codEmpresa', opts.empresa);
+        if (opts.delegacion !== undefined)
+            url.searchParams.set('codDelegacion', opts.delegacion);
+        if (opts.order !== undefined)
+            url.searchParams.set('order', opts.order);
+        const path = url.pathname + (url.search ? url.search : '');
+        const data = await this.get(path);
+        return { items: data.items, total: Number(data.total) };
+    }
+    /**
+     * Busca una cabecera de contrato por sus códigos naturales.
+     *
+     * No existe un endpoint GET singular para contratos pvss y el listado ignora
+     * `rQuery`, así que se pagina el listado (items=200, máximo permitido por el
+     * API) filtrando en cliente por CTRT_COD hasta encontrar la coincidencia.
+     *
+     * @param opts - Códigos naturales del contrato.
+     * @returns Cabecera del contrato.
+     * @throws FreematicaError('not_found') si no existe.
+     */
+    async getContrato(opts) {
+        const PAGE_SIZE = 200;
+        const MAX_PAGES = 100; // guardarraíl: 20.000 contratos
+        for (let page = 1; page <= MAX_PAGES; page++) {
+            const { items } = await this.listContratos({
+                empresa: opts.empresa,
+                delegacion: opts.delegacion,
+                page,
+                items: PAGE_SIZE,
+            });
+            const match = items.find((c) => String(c['CTRT_COD']) === opts.codContrato &&
+                String(c['CTRT_EMP']) === opts.empresa &&
+                (opts.delegacion === undefined || String(c['CTRT_DELEG']) === opts.delegacion));
+            if (match)
+                return match;
+            if (items.length < PAGE_SIZE)
+                break;
+        }
+        throw new FreematicaError('not_found', `Contrato no encontrado: empresa=${opts.empresa} delegacion=${opts.delegacion ?? '*'} codContrato=${opts.codContrato}`);
+    }
+    /**
+     * Lista paginada de servicios de un contrato.
+     *
+     * Endpoint: GET /pvss/v1/contratos/{idContrato}/servicios
+     *
+     * @param idContrato - idReg opaco del contrato (Base64 "EMP__DELEG__COD").
+     * @param opts - Paginación + order.
+     * @returns Lista paginada de servicios (campos CTRTS_*).
+     */
+    async listServiciosContrato(idContrato, opts = {}) {
+        const url = new URL(`https://placeholder/pvss/v1/contratos/${encodeURIComponent(idContrato)}/servicios`);
+        if (opts.items !== undefined)
+            url.searchParams.set('items', String(opts.items));
+        if (opts.page !== undefined)
+            url.searchParams.set('page', String(opts.page));
+        if (opts.order !== undefined)
+            url.searchParams.set('order', opts.order);
+        const path = url.pathname + (url.search ? url.search : '');
+        const data = await this.get(path);
+        return { items: data.items, total: Number(data.total) };
+    }
+    /**
+     * Detalle de un servicio de contrato por `idReg` opaco.
+     *
+     * Endpoint: GET /pvss/v2/contratos-servicios/{idreg}
+     *
+     * @param idReg - idReg opaco del servicio (Base64 "EMP__DELEG__CTRT__COD").
+     * @returns Servicio completo.
+     */
+    async getServicioContrato(idReg) {
+        return this.get(`/pvss/v2/contratos-servicios/${encodeURIComponent(idReg)}`);
+    }
+    /**
+     * Lista paginada de opcionales de contratos.
+     *
+     * Endpoint: GET /ppre/v2/contratos/opcionales
+     *
+     * @param opts - Paginación + order.
+     * @returns Lista paginada de opcionales (campos CON2_*).
+     */
+    async listContratosOpcionales(opts = {}) {
+        const url = new URL('https://placeholder/ppre/v2/contratos/opcionales');
+        if (opts.items !== undefined)
+            url.searchParams.set('items', String(opts.items));
+        if (opts.page !== undefined)
+            url.searchParams.set('page', String(opts.page));
+        if (opts.order !== undefined)
+            url.searchParams.set('order', opts.order);
+        const path = url.pathname + (url.search ? url.search : '');
+        const data = await this.get(path);
+        return { items: data.items, total: Number(data.total) };
+    }
+    /**
+     * Detalle de un registro de opcionales de contrato por `idReg` opaco.
+     *
+     * Endpoint: GET /ppre/v2/contratos/opcionales/{idReg}
+     */
+    async getContratoOpcionales(idReg) {
+        return this.get(`/ppre/v2/contratos/opcionales/${encodeURIComponent(idReg)}`);
+    }
+    // ---------------------------------------------------------------------------
+    // Contratos y Servicios (v0.7.0) — escritura (create/update, sin delete)
+    //
+    // Todas las operaciones de escritura se registran en el log (nivel info con
+    // la operación y claves del registro; nivel debug con el body completo) para
+    // soportar auditoría y rollback manual.
+    // ---------------------------------------------------------------------------
+    /**
+     * Alta de cabecera de contrato.
+     *
+     * Endpoint: POST /pvss/v2/contratos — body VoContratos.
+     * Campos requeridos por el API: CTRT_DELEG, CTRT_DES, CTRT_FECHA, CTRT_COD_CLI.
+     *
+     * @param body - Campos CTRT_* del contrato.
+     * @returns El contrato creado (VoContratos).
+     */
+    async createContrato(body) {
+        this.logWrite('createContrato', 'POST /pvss/v2/contratos', body);
+        return this.post('/pvss/v2/contratos', body);
+    }
+    /**
+     * Actualización de cabecera de contrato.
+     *
+     * Endpoint: PUT /pvss/v2/contratos/{idReg} — body VoContratos.
+     *
+     * @param idReg - idReg opaco del contrato.
+     * @param body - Campos CTRT_* a actualizar.
+     * @returns Respuesta del API.
+     */
+    async updateContrato(idReg, body) {
+        this.logWrite('updateContrato', `PUT /pvss/v2/contratos/${idReg}`, body);
+        return this.put(`/pvss/v2/contratos/${encodeURIComponent(idReg)}`, body);
+    }
+    /**
+     * Alta de un servicio en un contrato.
+     *
+     * Endpoint: POST /pvss/v2/contratos/{idReg}/servicios — body VoServicios.
+     * Campos requeridos por el API: CTRTS_EMP, CTRTS_DELEG, CTRTS_CTRT (los
+     * mismos valores codificados en el idReg del contrato).
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param body - Campos CTRTS_* del servicio.
+     * @returns El servicio creado (VoServicios).
+     */
+    async createServicioContrato(idContrato, body) {
+        this.logWrite('createServicioContrato', `POST /pvss/v2/contratos/${idContrato}/servicios`, body);
+        return this.post(`/pvss/v2/contratos/${encodeURIComponent(idContrato)}/servicios`, body);
+    }
+    /**
+     * Actualiza fechas de inicio y fin de un servicio.
+     *
+     * Endpoint: PUT /pvss/v2/contratos/{idContrato}/servicio/{idServicio}.
+     * Según el spec, este endpoint solo actualiza fecha inicio y fecha fin.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos CTRTS_* (fechas) a actualizar.
+     * @returns Respuesta del API.
+     */
+    async updateServicioFechas(idContrato, idServicio, body) {
+        this.logWrite('updateServicioFechas', `PUT /pvss/v2/contratos/${idContrato}/servicio/${idServicio}`, body);
+        return this.put(`/pvss/v2/contratos/${encodeURIComponent(idContrato)}/servicio/${encodeURIComponent(idServicio)}`, body);
+    }
+    /**
+     * Actualiza los datos de facturación de un servicio.
+     *
+     * Endpoint: PUT /pvss/v2/contratos/{idContrato}/servicios-facturacion/{idServicio}.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos CTRTF_* a actualizar.
+     * @returns Respuesta del API.
+     */
+    async updateServicioFacturacion(idContrato, idServicio, body) {
+        this.logWrite('updateServicioFacturacion', `PUT /pvss/v2/contratos/${idContrato}/servicios-facturacion/${idServicio}`, body);
+        return this.put(`/pvss/v2/contratos/${encodeURIComponent(idContrato)}/servicios-facturacion/${encodeURIComponent(idServicio)}`, body);
+    }
+    /**
+     * Alta de un texto de facturación de un servicio.
+     *
+     * Endpoint: POST /pvss/v2/contratos/{idContrato}/servicios-facturacion-txt/{idServicio}.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos CTRTFL_* del texto.
+     * @returns Respuesta del API.
+     */
+    async createServicioFacturacionTxt(idContrato, idServicio, body) {
+        this.logWrite('createServicioFacturacionTxt', `POST /pvss/v2/contratos/${idContrato}/servicios-facturacion-txt/${idServicio}`, body);
+        return this.post(`/pvss/v2/contratos/${encodeURIComponent(idContrato)}/servicios-facturacion-txt/${encodeURIComponent(idServicio)}`, body);
+    }
+    /**
+     * Alta de un registro de histórico de precios de un servicio.
+     *
+     * Endpoint: POST /pvss/v2/contratos/{idContrato}/servicios-historico-precios/{idServicio}.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos SERVHPR_* del histórico.
+     * @returns Respuesta del API (VoServiciosHistPr).
+     */
+    async createServicioHistoricoPrecios(idContrato, idServicio, body) {
+        this.logWrite('createServicioHistoricoPrecios', `POST /pvss/v2/contratos/${idContrato}/servicios-historico-precios/${idServicio}`, body);
+        return this.post(`/pvss/v2/contratos/${encodeURIComponent(idContrato)}/servicios-historico-precios/${encodeURIComponent(idServicio)}`, body);
+    }
+    /**
+     * Actualiza un registro de histórico de precios de un servicio.
+     *
+     * Endpoint: PUT /pvss/v2/contratos/{idContrato}/servicios-historico-precios/{idServicio}.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos SERVHPR_* a actualizar.
+     * @returns Respuesta del API.
+     */
+    async updateServicioHistoricoPrecios(idContrato, idServicio, body) {
+        this.logWrite('updateServicioHistoricoPrecios', `PUT /pvss/v2/contratos/${idContrato}/servicios-historico-precios/${idServicio}`, body);
+        return this.put(`/pvss/v2/contratos/${encodeURIComponent(idContrato)}/servicios-historico-precios/${encodeURIComponent(idServicio)}`, body);
+    }
+    /**
+     * Alta de un registro de opcionales de contrato.
+     *
+     * Endpoint: POST /ppre/v2/contratos/opcionales — body VoContratosOpcionales.
+     * Campos requeridos por el API: CON2_CODEMP, CON2_DELEG, CON2_TIPOCONT,
+     * CON2_NUMCONT, CON2_FCHCONT.
+     *
+     * @param body - Campos CON2_* del registro.
+     * @returns El registro creado.
+     */
+    async createContratoOpcionales(body) {
+        this.logWrite('createContratoOpcionales', 'POST /ppre/v2/contratos/opcionales', body);
+        return this.post('/ppre/v2/contratos/opcionales', body);
+    }
+    /**
+     * Actualiza un registro de opcionales de contrato.
+     *
+     * Endpoint: PUT /ppre/v2/contratos/opcionales/{idReg}.
+     *
+     * @param idReg - idReg opaco del registro de opcionales.
+     * @param body - Campos CON2_* a actualizar.
+     * @returns Respuesta del API.
+     */
+    async updateContratoOpcionales(idReg, body) {
+        this.logWrite('updateContratoOpcionales', `PUT /ppre/v2/contratos/opcionales/${idReg}`, body);
+        return this.put(`/ppre/v2/contratos/opcionales/${encodeURIComponent(idReg)}`, body);
+    }
+    /**
+     * Log de auditoría de operaciones de escritura.
+     *
+     * Nivel info: operación + endpoint + claves del body (sin valores).
+     * Nivel debug: body completo, para poder reconstruir la operación.
+     */
+    logWrite(operation, endpoint, body) {
+        logger.info({ operation, endpoint, fields: Object.keys(body) }, 'freematica write');
+        logger.debug({ operation, endpoint, body }, 'freematica write body');
+    }
+    // ---------------------------------------------------------------------------
     // Internal helpers
     // ---------------------------------------------------------------------------
     async listResource(path, opts) {