@controldealquiler/sdk 1.2.2 → 1.3.1

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 {
@@ -256,7 +252,11 @@ interface Borradores {
         local: ResultadoLecturaAlta | null;
     }>;
 }
-declare function crearBorradores(http: Http): Borradores;
+/** `permitir` (por defecto): ante el 409 se sube el fichero por multipart. `rechazar`: no sale ningún multipart; el 409 se relanza. */
+type LecturaEnServidor = 'permitir' | 'rechazar';
+declare function crearBorradores(http: Http, o?: {
+    lecturaEnServidor?: LecturaEnServidor;
+}): Borradores;
 
 /** Todas las cajas de un fichero del alta: `acta` (0 o 1 por contrato) y `movimientos` solo van con paquete. */
 declare const CAJAS: readonly ["contract", "tenant_id", "other", "acta", "movimientos", "foto"];
@@ -354,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[];
@@ -378,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;
@@ -395,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;
@@ -425,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;
@@ -580,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];
@@ -667,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>;
 
@@ -692,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;
 }
@@ -706,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;
@@ -724,16 +702,20 @@ 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;
     dormir?: (ms: number) => Promise<void>;
     /** Ficheros de una vivienda procesados a la vez (1 a 8). Si no se fija, el SDK usa la que sugiere `GET /v1/yo` o, si falta, 4. La API admite 10 peticiones/s por cuenta, ráfaga de 50. */
     concurrenciaFicheros?: number;
+    /**
+     * Qué hacer si la API pasa a leer en el servidor (`409 AGENCIA_MODO_SERVIDOR`). `'permitir'` (por defecto): el SDK sube el fichero
+     * por multipart, sin el cifrado de extremo a extremo. `'rechazar'`: no sale ningún multipart; `leer`, el alta y `crearBorradores`
+     * fallan (el alta con `ErrorAlta`, `corta: true`, `reintentable: false`).
+     */
+    lecturaEnServidor?: LecturaEnServidor;
 }
 declare function crearCliente(o: OpcionesCliente): ClienteCda;
 
 export { ErrorAlta, ErrorApiSdk, ErrorClaveIntegracion, ErrorDeEntorno, ErrorFirmaWebhook, FOTO_BYTES_OBJETIVO, FOTO_CALIDAD, FOTO_CALIDAD_2, FOTO_LADO_MAX, TIPOS_WEBHOOK, TOLERANCIA_WEBHOOK_S, TOPE_BYTES, URL_BASE_SANDBOX, abrirContenidoFichero, abrirJson, abrirNombreFichero, abrirSobreBytes, admiteIdempotencia, base64ToBytes, bytesToBase64, clasificar, codigoDe, crearAlta, crearBorradores, crearCliente, crearClientes, crearGestion, crearHttp, crearMantenimiento, crearVarios, descifradorDeClave, descifradorDeFichero, envolver, esperaDeRetryAfter, etiquetaIfMatch, importarPrivadaPkcs8, leerFicheroLocal, prepararFoto, reenvolverClave, sellarFichero, sellarJson, sellarSobreB64, sha256Hex, sobreDeB64, verificarWebhook };
-export type { Borradores, BuzonApi, CabecerasWebhook, ClienteApi, ClienteCda, Clientes, ClientesGestion, Consejo, ContextoAlta, Creado, Creditos, DepsAlta, DepsGestion, DepsMantenimiento, Descifrador, DestinoWebhook, EdicionCliente, EntradaAlta, EntregaWebhook, ErrorCliente, Escrito, FallidoAlta, FicheroAlta, FicheroSellado, FijarRenovacion, Gestion, Http, Incluir, InformeVarios, LectorVigente, Mantenimiento, ModoRenovacion, MotivoFirmaWebhook, OpcionesCliente, OpcionesEscritura, OpcionesHttp, OpcionesLector, OpcionesListar, OpcionesVarios, OpcionesVerificar, OrigenClaveIntegracion, PaginaClientes, PasoAlta, Peticion, ReglaRenovacion, Remitentes, RenovacionApi, ResultadoAlta, ResultadoFotoSdk, ResultadoMantenimiento, SalidaLectorLocal, Sobre, SobreApi, SobreB64Cliente, TipoWebhook, ViviendaAlta, ViviendaApi, ViviendaEdicion, Viviendas, WebhookVerificado, Webhooks };
+export type { Borradores, BuzonApi, CabecerasWebhook, ClienteApi, ClienteCda, Clientes, ClientesGestion, Consejo, ContextoAlta, Creado, Creditos, DepsAlta, DepsGestion, DepsMantenimiento, Descifrador, DestinoWebhook, EdicionCliente, EntradaAlta, EntregaWebhook, ErrorCliente, Escrito, FallidoAlta, FicheroAlta, FicheroSellado, FijarRenovacion, Gestion, Http, Incluir, InformeVarios, LectorVigente, LecturaEnServidor, Mantenimiento, ModoRenovacion, MotivoFirmaWebhook, OpcionesCliente, OpcionesEscritura, OpcionesHttp, OpcionesLector, OpcionesListar, OpcionesVarios, OpcionesVerificar, OrigenClaveIntegracion, PaginaClientes, PasoAlta, Peticion, ReglaRenovacion, Remitentes, RenovacionApi, ResultadoAlta, ResultadoFotoSdk, ResultadoMantenimiento, SalidaLectorLocal, Sobre, SobreApi, SobreB64Cliente, TipoWebhook, ViviendaAlta, ViviendaApi, ViviendaEdicion, Viviendas, WebhookVerificado, Webhooks };