@controldealquiler/sdk 1.3.0 → 1.3.1

package/README.md

@@ -211,6 +211,10 @@ Se configura por entorno:
 
 `controldealquiler` sin argumentos muestra la ayuda de cada comando.
 
+## Cambios en 1.3.1
+
+- Limpia los tipos publicados: quita comentarios internos y opciones reservadas a pruebas. Sin cambios de comportamiento.
+
 ## Cambios en 1.3.0
 
 - Nueva opción `lecturaEnServidor: 'permitir' | 'rechazar'` (por defecto `'permitir'`, como hasta ahora). Con `'rechazar'`, el `409 AGENCIA_MODO_SERVIDOR` no sube el fichero por multipart: `borradores.leer`, `crearBorradores` y el alta fallan, y el alta lanza `ErrorAlta` con `corta: true` y `reintentable: false`.

package/dist/index.d.ts

@@ -49,13 +49,12 @@ interface Sobre {
     iv: Uint8Array;
 }
 interface FicheroSellado {
-    /** iv||cipher: se sube tal cual al bucket (formato del vault). */
+    /** Contenido cifrado, listo para subir tal cual. */
     blob: Uint8Array;
     wrapped_file_key: Uint8Array;
     nombre_cipher: Uint8Array;
     nombre_iv: Uint8Array;
 }
-/** (Sin AAD en AES-GCM, compatible con `envelope.ts` tal cual: el formato no ata el sobre a su cliente.) */
 /** Sella un JSON con la pública del destinatario (un único sobre). */
 declare function sellarJson(valor: unknown, publicaSpki: Uint8Array): Promise<Sobre>;
 /** Abre un sobre con la privada (CryptoKey RSA-OAEP con `decrypt`). */
@@ -96,7 +95,7 @@ interface Descifrador {
     publicaAgenciaSpki(): Promise<string>;
     /**
      * La privada de sobres de la agencia como clave no extraíble, solo en memoria del proceso. La usa `clientes.crear` para
-     * re-envolver las claves de los ficheros hacia la llave efímera del alta (el mismo `sellarBorradorParaEfimera` del panel).
+     * re-envolver las claves de los ficheros hacia la llave efímera del alta, igual que el panel.
      */
     clavePrivadaSobres(): Promise<CryptoKey>;
 }
@@ -140,8 +139,8 @@ interface ParsedLeaseContract {
     /** Dirección de la vivienda tal como consta (una línea, sin trocear), máx. 200 caracteres. */
     property_address: string | null;
     /**
-     * Solo el lector sin IA de las agencias (`lib/agencia/lectores/contrato.ts`) lo fija, tras parsear (este parser nunca lo lee del JSON): la RC de la VIVIENDA que se importa a su
-     * ficha (ya validada por dígitos de control), o null si el contrato no la fija. Ausente en la lectura por IA.
+     * Referencia catastral de la vivienda que se importa a su ficha (ya validada por dígitos de control), o null si el
+     * contrato no la fija. Solo la rellena la lectura sin IA de las agencias; ausente en la lectura por IA.
      */
     cadastral_ref_vivienda?: string | null;
 }
@@ -156,7 +155,7 @@ interface VentanaEjercicios {
     caducaAntesDe: string | null;
 }
 
-/** Lo que dice la certificación de la agencia (`agencia_lector`): qué parser y qué conceptos están certificados. */
+/** Lo que dice la certificación de la agencia: qué parser y qué conceptos están certificados. */
 interface LectorCertificado {
     parser: string;
     conceptos: string[];
@@ -208,9 +207,8 @@ type ResultadoLecturaAlta = {
     /** Filas leídas pero fuera de la ventana de ejercicios: se quitan con aviso. */
     filasFuera: number;
     /**
-     * Rótulo de cada fila de `filas` (mismo orden, ≤200 caracteres): texto libre del PDF. NUNCA va a la BD ni a la
-     * respuesta del servidor (`lecturaAGuardar` y `respuestaDe` eligen campos a mano): solo lo usa el navegador de la
-     * agencia para el sobre E2EE del titular, donde es el concepto de la transacción.
+     * Rótulo de cada fila de `filas` (mismo orden, ≤200 caracteres): texto libre del PDF. Nunca viaja a la API:
+     * solo lo usa el navegador de la agencia para el sobre cifrado del titular, donde es el concepto de la transacción.
      */
     rotulos: string[];
 } | {
@@ -219,7 +217,7 @@ type ResultadoLecturaAlta = {
     transitorio: boolean;
 };
 
-/** Mismo tope que el servidor y el navegador (`leer-alta-navegador.ts`, `leer-fichero.ts`). */
+/** Mismo tope que el servidor y el navegador (el mismo que aplica el panel). */
 declare const TOPE_BYTES = 4000000;
 /** Lector vivo de la agencia: `parser` y conceptos certificados (constantes del sistema, sin PII). */
 type LectorVigente = LectorCertificado;
@@ -237,8 +235,6 @@ interface OpcionesLector {
     /** El servidor aplica la ventana: aquí se lee con una ventana abierta, igual que el navegador. */
     ventana?: VentanaEjercicios;
     mime?: string;
-    /** Solo para los tests: sustituye a pdf.js. */
-    extraer?: (b: Uint8Array) => Promise<string | null>;
 }
 declare function leerFicheroLocal(bytes: Uint8Array, a: OpcionesLector): Promise<SalidaLectorLocal>;
 interface Borradores {
@@ -358,8 +354,7 @@ interface ViviendaAlta {
     municipio?: string;
     direccion: string;
     /**
-     * Código postal (5 cifras), OBLIGATORIO: el sobre de la vivienda lo exige (`sobreViviendaSchema`) y el dueño lo ve. Desvío
-     * del plan (su interfaz no lo traía); nunca se inventa uno (decisión de la Reina, 28-10).
+     * Código postal (5 cifras), obligatorio: el sobre de la vivienda lo exige y el titular lo ve. El SDK nunca inventa uno.
      */
     cp: string;
     ficheros: FicheroAlta[];
@@ -382,13 +377,11 @@ interface DepsAlta {
     http: Http;
     borradores: Borradores;
     descifrador: Descifrador;
-    /** `fetch` para subir los objetos a la URL firmada del Storage. */
+    /** `fetch` para subir los ficheros a la URL firmada. */
     fetch?: typeof fetch;
     /** Origen del sitio (`https://controldealquiler.com`) para componer el enlace. */
     origen: string;
-    /** Solo para los tests: sustituye a pdf.js. */
-    extraer?: OpcionesLector['extraer'];
-    /** «Hoy» de Madrid para validar los contratos; por defecto `lib/time/madrid.ts`. */
+    /** «Hoy» de Madrid para validar los contratos; por defecto, la fecha de hoy en Madrid. */
     hoy?: () => string;
     /** Espera entre sondeos del lote y entre reintentos de lectura (ms). */
     intervaloMs?: number;
@@ -399,18 +392,16 @@ interface DepsAlta {
      * Ficheros de una misma vivienda que se suben y leen a la vez (entero de 1 a 8; fuera de rango se acota). Si no se fija,
      * se usa la sugerencia del servidor (`GET /v1/yo` → `limites.concurrencia_ficheros`) y, si falta o falla, 4.
      * 1 los procesa uno tras otro. Las viviendas siguen en serie. Cada fichero cuesta unas 3 llamadas a la API y la API admite
-     * 10 peticiones/s por cuenta con ráfaga de 50 (`apps/web/lib/api/limites.ts`): un 429 se reintenta con `Retry-After`.
+     * 10 peticiones/s por cuenta con ráfaga de 50: un 429 se reintenta con `Retry-After`.
      */
     concurrenciaFicheros?: number;
-    /** Uso interno: la sugerencia del servidor, memorizada por cliente (`concurrenciaDelServidor`). */
-    concurrenciaSugerida?: () => Promise<number>;
 }
 /** `crearAlta(d, e)` = `crearAltaConContexto(d, e)`. Lanza SIEMPRE `ErrorAlta` (nada más). */
 declare function crearAlta(deps: DepsAlta, e: EntradaAlta): Promise<ResultadoAlta>;
 interface Clientes {
     /**
      * Alta de un cliente con sus viviendas y ficheros por el circuito del panel. Idempotente por `ref`.
-     * `previo` es de uso interno de `crearVarios` y del CLI: arrastra `creado: 'desconocido'` entre intentos de una misma `ref`.
+     * `previo` está reservado para los reintentos de `crearVarios`: no hace falta pasarlo.
      */
     crear(e: EntradaAlta, previo?: {
         creado: Creado;
@@ -429,7 +420,7 @@ interface ResultadoMantenimiento {
     imposibles: number;
     /** Un error de un cliente (lote inválido, fallo del servidor…) no tumba la pasada: se recoge aquí y se sigue con los demás. */
     errores: ErrorCliente[];
-    /** Sobres que la privada de la agencia no abre o que no validan: se quedan pendientes (ver el residual de F1 arriba). */
+    /** Sobres que la privada de la agencia no abre o que no validan: se quedan pendientes. */
     sobresSinAbrir: number;
     /** `false` si en algún momento faltó una cabecera `Date` válida del servidor: en ese caso no se declaró nada. */
     relojServidor: boolean;
@@ -584,9 +575,7 @@ interface RenovacionApi {
     fijar(f: FijarRenovacion): Promise<unknown>;
 }
 /**
- * Tipos públicos de webhook (v10 § 4.8). Viven como DATOS en `api_webhook_tipo` (migración, columna A); el SDK es
- * público y no importa del servidor, así que los repite aquí y `tests/api/webhook-tipos-sdk.test.ts` los compara con la
- * migración para que no se desfasen.
+ * Tipos de evento de webhook que la API puede enviar.
  */
 declare const TIPOS_WEBHOOK: readonly ["cliente.activado", "cliente.ido", "lote.terminado", "credencial.caduca_pronto", "mantenimiento.pendiente"];
 type TipoWebhook = (typeof TIPOS_WEBHOOK)[number];
@@ -671,20 +660,7 @@ type ResultadoFotoSdk = {
     ok: false;
     error: 'IMAGEN_NO_PROCESABLE';
 };
-/** Lo mínimo de `sharp` que usamos (se tipa a mano: la dependencia es opcional y puede no estar instalada). */
-interface SharpInstancia {
-    rotate(): SharpInstancia;
-    resize(o: Record<string, unknown>): SharpInstancia;
-    clone(): SharpInstancia;
-    jpeg(o: {
-        quality: number;
-    }): SharpInstancia;
-    toBuffer(): Promise<Uint8Array>;
-}
-type SharpFn = (entrada: Uint8Array, opciones?: Record<string, unknown>) => SharpInstancia;
 interface DepsFoto {
-    /** Solo para los tests: sustituye a la carga de `sharp` (`null` = no instalado). */
-    cargarSharp?: () => Promise<SharpFn | null>;
 }
 declare function prepararFoto(bytes: Uint8Array, mime: string, deps?: DepsFoto): Promise<ResultadoFotoSdk>;
 
@@ -696,8 +672,6 @@ declare class ErrorFirmaWebhook extends Error {
 }
 type CabecerasWebhook = Headers | Record<string, string | string[] | undefined>;
 interface OpcionesVerificar {
-    /** «Ahora» en milisegundos Unix; por defecto `Date.now()`. Solo para tests. */
-    ahora?: () => number;
     /** Ventana en segundos a cada lado (por defecto 300). */
     toleranciaS?: number;
 }
@@ -710,7 +684,7 @@ interface WebhookVerificado {
 declare function verificarWebhook(cuerpo: string | Uint8Array, cabeceras: CabecerasWebhook, secreto: string | readonly string[], opciones?: OpcionesVerificar): WebhookVerificado;
 
 interface ClienteCda {
-    /** Llamada de bajo nivel; las tareas siguientes cuelgan de aquí `clientes`, `borradores`, `mantenimiento`. */
+    /** Llamada de bajo nivel a la API; sobre ella se construyen `clientes`, `borradores` y `mantenimiento`. */
     peticion<T = unknown>(p: Peticion): Promise<T>;
     http: Http;
     descifrador: Descifrador;
@@ -728,8 +702,6 @@ interface OpcionesCliente {
     baseUrl?: string;
     descifrador: Descifrador;
     fetch?: typeof fetch;
-    /** Solo para los tests: sustituye a pdf.js al leer actas, contratos y movimientos. */
-    extraer?: OpcionesLector['extraer'];
     hoy?: () => string;
     intervaloMs?: number;
     maxEsperaMs?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@controldealquiler/sdk",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "license": "SEE LICENSE IN LICENSE",
   "private": false,
   "type": "module",
@@ -14,8 +14,8 @@
   },
   "scripts": {
     "build": "node build.mjs",
-    "prepublishOnly": "node build.mjs && vitest run test/tipos-paquete.test.ts",
-    "test:tipos": "vitest run test/tipos-paquete.test.ts",
+    "prepublishOnly": "node build.mjs && vitest run test/tipos-paquete.test.ts test/vocabulario-interno.test.ts",
+    "test:tipos": "vitest run test/tipos-paquete.test.ts test/vocabulario-interno.test.ts",
     "test": "vitest run --passWithNoTests"
   },
   "devDependencies": {